logo
API docs by Redocly

Metasys REST API (4.487)

Download OpenAPI specification:Download

Introduction

The Metasys REST API is the exposed interface for accessing data from a Johnson Controls® Metasys system. This spec documents v4 of the API first released as part of Metasys 12.0. This documentation was last updated on February 9, 2023, 3:00 PM (UTC).

This version of the documentation includes INTERNAL operations which are only for use by approved Johnson Controls teams/projects.

This version of the documentation includes PRIVATE operations which are only to be used by Metasys developers for Metasys products. These operations should not be shared with other teams within Johnson Controls, nor should they be shared with third parties outside of Johnson Controls.

Metasys is a network-based building automation system (BAS) that operates the mechanical and electrical equipment in your building. For an introduction to Metasys, refer to Metasys System in Metasys System Configuration Guide. For a glossary of Metasys terms, refer to Metasys System Glossary. For additional information on Metasys, search the Johnson Controls documentation site Knowledge Exchange.

This specification defines the operations you can use to retrieve data through the API. For further information on the Metasys API, including tutorials, see the Metasys API home page.

© 2022 Johnson Controls Tyco IP Holdings LLP.

Base URL

This documentation is for Metasys 12.0 which ships with version 4 of the Metasys Server.

The base path for the API is https://{hostname}/api/v4 where {hostname} is the host name of your Metasys server.

API Version Notes

Multiple versions of this API may be supported on one release of Metasys. At Metasys 12.0, the supported versions are v2, v3, and v4.

Note: v1 is not supported by Metasys 12.0.

You must specify which version you intend to use in the URL, using the format v[#].

For example, https://localhost/api/v4/spaces for version 4 of spaces.

Documentation for v3 and earlier can be found here.

Version Response Behavior

The Content-Type header of the response will always contain (in part) the version of the API that was used to serve the request. This allows you to identify which version of the API was utilized.

For example, Content-Type: application/vnd.metasysapi.v4+json for version 4.

Licensed Operations

You must obtain an additional license to access some operations. For more information, refer to the Licensing information and Software information sections in Metasys System Software Purchase Options Product Bulletin (LIT-12011703).

Monitoring and Commanding API license

The Monitoring and Commanding API enables reading, writing, and commanding one or more Metasys objects/properties, including Present Value. This API succeeds the Metasys System Secure Data Access dynamic link library (MSSDA DLL).

The following operations require the Monitoring and Commanding API license:

Case Sensitivity Rules

In general, you should assume that all URLs, parameter names, parameter values, payload property names and payload property values are case sensitive. For example:

  • All attributes of objects are case sensitive. For example, many objects have an attribute named presentValue. It is case sensitive and must always be spelled presentValue.
  • Enumeration set names and set members are case sensitive (for example, reliabilityEnumSet.reliable, displayPrecisionEnumSet.displayPrecision1, and writePriorityEnumSet.priorityDefault).

Pagination

For operations where page and pageSize is allowed, the default page number will be 1 and is 1-based for all paths while the default pageSize will vary between paths. The page parameter indicates the page number of items to return from the path. The pageSize parameter indicates the maximum number of items in the response from the path.

Payloads returned by pagination-enabled paths have a similar structure. A total property indicates the total number of items included in all pages. A next and previous property supplies a link to the next and previous page of data, respectively. These properties can be empty if irrelevant (for example, if it is the first/last page, or there is only one page of data). The items property contains the data included in the page.

Sorting Rules

For operations where a sort query parameter is allowed, the supplied value should be in the format of a single attribute name, optionally prefixed with - to indicate descending sort order (ascending order is used if no prefix is supplied).

DateTimes

All date-times in the alarms, audits, activities, and samples operations are ISO-8601 encoded strings in UTC. Other operations, such as objects, use a proprietary structure further described in supporting documentation.

Validation

There are some general rules that apply across all operations. If certain provided inputs are invalid or preconditions are not met, the API will respond with an appropriate error to indicate what went wrong.

Condition Error Details
Invalid request body 400 (Bad Request) A body is provided which does not adhere to the expected format and/or schema
Missing required parameter 400 (Bad Request) A parameter marked required in this document is not included in the request
Parameter incorrect type 400 (Bad Request) A parameter is included with a value of the wrong type (for example, number is expected and string is provided)
Parameter out of range 400 (Bad Request) A numeric parameter is included but the value is outside the allowed range
Parameter not in set 400 (Bad Request) A string parameter has a set of predefined valid values, and the value provided is not included in that set
Parameter not in correct format 400 (Bad Request) A string parameter with expected format is provided in the wrong format
Unsupported Content-Type 400 (Bad Request) An unsupported Content-Type header is provided
User not authenticated 401 (Unauthorized) The auth token supplied with the request is missing, invalid, or expired
Record not authorized 403 (Forbidden) The user is not authorized to view data matching the provided identifier or too many requests
Invalid user type 403 (Forbidden) Not an "API user"; not all user accounts have API access
Identifier not found 404 (Not Found) An identifier is provided that does not match any known data
The resource already exists 409 (Conflict) The resource already exists
Internal Server Error 500 (Internal Server Error) An unexpected error occurred
The device is not supported 501 (Not Implemented) The server does not support the functionality required to fulfill the request
The device is offline 503 (Service Unavailable) The device is currently offline and unable to serve the request

Schemas in Response Payloads

The response payload of some operations in this document have a section of information labeled schema. This section of information includes important pieces of metadata about the item or items attributes that gives better context to the meaning of attribute values. This section follows JSON Schema specification with added custom annotation keywords.

Security

Bearer-Authentication

Most of the calls in the API use bearer token authentication. What this means is that these requests require an Authorization header to be set to a value with the following format: Bearer: {accessToken}. Use the /login operation to request an accessToken. An example of the full header would look like the following: Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1....

Note: This example access token is truncated.

The expiration time of the access token is based on the user's Metasys profile.

Note: If the expiration time of the access token is greater than 60 minutes from issue, disregard and refresh before 60 minutes to prevent session expiration. The next version of the API will provide the correct expiration time.

Security Scheme Type: HTTP
HTTP Authorization Scheme: bearer
Bearer format: JWT

API-Key-Authentication

The Streaming operation is the only operation to use API key authentication, because web browsers do not allow setting custom headers when initiating Server Sent Event connections.

Security Scheme Type: API Key
Query parameter name: access_token

activities

This section describes the operations you can perform on activities. Activities are a superset of all alarms and audits in a Metasys system. Use activities operations to view audits and alarms. Apply filters to further refine the results.

Activities Event Subscriptions

Subscribe for activity-related events to receive updates when activities are created, discarded, acknowledged, or annotated.

Subscribing

To subscribe for activity-related events, complete the following steps:

  1. Open a stream with the Get a stream operation. Take note of the stream ID.
  2. Use Get Activities and include a METASYS-SUBSCRIBE header with the stream ID.

Note: Any filters added to the original GET operation also apply the event subscription.

Unsubscribing

To unsubscribe from an activities event subscription, complete the following steps:

  1. Get the METASYS-SUBSCRIPTION-LOCATION from the subscribe operation response.
  2. Issue a Delete activities subscription request to METASYS-SUBSCRIPTION-LOCATION.

See also:

Events

There are five event types sent by the activities subscription: acknowledged, annotate, discard, new, and heartbeat.

  • activity.heartbeat - A heartbeat event is sent to show that the subscription is still alive. A heartbeat is a JSON string with the current UTC date time in ISO 8601 format and is sent every 30 seconds.

    Heartbeat Payload Example 
    {
  "currentTime": "2021-02-16T16:21:10.23Z",
  "subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"]
}

  • activity.alarm.ack - An alarm acknowledge event is sent to indicate that the management status has changed to acknowledged.

    Acknowledged Alarm Payload Example 
    {
  "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
  "activity": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
    "objectName": "OA_T",
    "activityManagementStatus": "acknowledged",
    "creationTime": "2021-02-16T20:30:00Z",
    "spaces": [
      {
        "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
        "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
        "name": "Floor 1",
        "spaceUrl": "https://{hostname}/api/v4/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "equipment": [
      {
        "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
        "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
        "equipmentName": "Engine1",
        "shortName": null,
        "equipmentUrl": "https://{hostname}/api/v4/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "objectUrl": "https://{hostname}/api/v4/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
    "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
    "alarm": {
      "message": "",
      "alarmGeneratorObject": {
        "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
        "referencedObject": {
          "objectUrl": "https://{hostname}/api/v4/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
        }
      },
      "isAckRequired": true,
      "acknowledgedTime": "2021-02-16T20:31:02Z",
      "type": "alarmValueEnumSet.avHiAlarm",
      "priority": 70,
      "category": "objectCategoryEnumSet.generalCategory",
      "annotationsUrl": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "triggerValue": {
        "item": "2.0",
        "schema": {
          "type": "string",
          "metasysType": "string",
          "units": {
            "id": "unitEnumSet.degF",
            "title": "deg F"
          }
        }
      },
      "description": ""
    }
  },
  "effectivePermission": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "canAcknowledge": true,
    "canDiscard": true,
    "canAnnotate": true
  }
}

  • activity.alarm.annotate - An alarm annotate event is sent when an annotation is added to an alarm activity, providing the information for the annotated alarm.

    Annotate Alarm Payload Example 
    {
  "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
  "activity": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
    "objectName": "OA_T",
    "activityManagementStatus": "pending",
    "creationTime": "2021-02-16T20:30:00Z",
    "spaces": [
      {
        "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
        "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
        "name": "Floor 1",
        "spaceUrl": "https://{hostname}/api/v4/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "equipment": [
      {
        "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
        "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
        "equipmentName": "Engine1",
        "shortName": null,
        "equipmentUrl": "https://{hostname}/api/v4/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "objectUrl": "https://{hostname}/api/v4/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
    "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
    "alarm": {
      "message": "",
      "alarmGeneratorObject": {
        "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
        "referencedObject": {
          "objectUrl": "https://{hostname}/api/v4/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
        }
      },
      "isAckRequired": true,
      "acknowledgedTime": "2021-02-16T20:31:02Z",
      "type": "alarmValueEnumSet.avHiAlarm",
      "priority": 70,
      "category": "objectCategoryEnumSet.generalCategory",
      "annotationsUrl": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "triggerValue": {
        "item": "2.0",
        "schema": {
          "type": "string",
          "metasysType": "string",
          "units": {
            "id": "unitEnumSet.degF",
            "title": "deg F"
          }
        }
      },
      "description": ""
    }
  },
  "effectivePermission": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "canAcknowledge": true,
    "canDiscard": true,
    "canAnnotate": true
  }
}

  • activity.alarm.discard - An alarm discard event is sent when the management status of an alarm activity changes to discarded.

    Discard Alarm Payload Example 
    {
  "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
  "activity": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
    "objectName": "OA_T",
    "activityManagementStatus": "discarded",
    "creationTime": "2021-02-16T20:30:00Z",
    "spaces": [
      {
        "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
        "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
        "name": "Floor 1",
        "spaceUrl": "https://{hostname}/api/v4/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "equipment": [
      {
        "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
        "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
        "equipmentName": "Engine1",
        "shortName": null,
        "equipmentUrl": "https://{hostname}/api/v4/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "objectUrl": "https://{hostname}/api/v4/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
    "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
    "alarm": {
      "message": "",
      "alarmGeneratorObject": {
        "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
        "referencedObject": {
          "objectUrl": "https://{hostname}/api/v4/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
        }
      },
      "isAckRequired": true,
      "acknowledgedTime": "2021-02-16T20:31:02Z",
      "type": "alarmValueEnumSet.avHiAlarm",
      "priority": 70,
      "category": "objectCategoryEnumSet.generalCategory",
      "annotationsUrl": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "triggerValue": {
        "item": "2.0",
        "schema": {
          "type": "string",
          "metasysType": "string",
          "units": {
            "id": "unitEnumSet.degF",
            "title": "deg F"
          }
        }
      },
      "description": ""
    }
  },
  "effectivePermission": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "canAcknowledge": true,
    "canDiscard": true,
    "canAnnotate": true
  }
}

  • activity.alarm.new - A new alarm event is sent when an alarm activity is created.

    New Alarm Payload Example 
    {
  "subscriptionIds": ["788fc8af-ff49-4501-b85b-e3d407a38a9e"],
  "activity": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "itemReference": "{hostname}:{deviceHostname}/AHU1.OA_T",
    "objectName": "OA_T",
    "activityManagementStatus": "pending",
    "creationTime": "2021-02-16T20:30:00Z",
    "spaces": [
      {
        "id": "20b27e9a-d721-5e88-9942-85297cc57ea1",
        "itemReference": "{hostname}:{deviceHostname}/Generic 1.Building 1.Floor 1",
        "name": "Floor 1",
        "spaceUrl": "https://{hostname}/api/v4/space/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "equipment": [
      {
        "id": "4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f",
        "itemReference": "{hostname}:{deviceHostname}/equipment.Engine1",
        "equipmentName": "IDU1",
        "shortName": null,
        "equipmentUrl": "https://{hostname}/api/v4/equipment/4e0df8ec-c641-5fd0-9ed6-f2d980b1d26f"
      }
    ],
    "objectUrl": "https://{hostname}/api/v4/objects/16defc31-1333-5379-82e7-576a6f1e8b50",
    "objectId": "16defc31-1333-5379-82e7-576a6f1e8b50",
    "alarm": {
      "message": "",
      "alarmGeneratorObject": {
        "objectReference": "{hostname}:{deviceHostname}/AHU1.OA_T.Alarm1",
        "referencedObject": {
          "objectUrl": "https://{hostname}/api/v4/objects/bfcc3fce-a182-53c0-a529-268f8184496b"
        }
      },
      "isAckRequired": true,
      "type": "alarmValueEnumSet.avHiAlarm",
      "priority": 70,
      "category": "objectCategoryEnumSet.generalCategory",
      "annotationsUrl": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f",
      "triggerValue": {
        "item": "2.0",
        "schema": {
          "type": "string",
          "metasysType": "string",
          "units": {
            "id": "unitEnumSet.degF",
            "title": "deg F"
          }
        }
      },
      "description": ""
    }
  },
  "effectivePermission": {
    "id": "6443a123-ddcd-47e7-9828-d872db6a7b4f",
    "canAcknowledge": true,
    "canDiscard": true,
    "canAnnotate": true
  }
}

  • activity.audit.new - A new audit event is sent when an audit activity is created.

    New Audit Payload Example 
    {
  "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
  "activity": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "itemReference": "{hostname}:{deviceHostname}",
    "objectName": "MS-NAE5510-3",
    "activityManagementStatus": "pending",
    "creationTime": "2021-02-16T16:21:10.23Z",
    "objectUrl": "https://{hostname}/api/v4/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
    "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
    "audit": {
      "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
      "status": null,
      "preData": null,
      "postData": {
        "item": "10.10.198.131",
        "schema": {
          "type": "string",
          "metasysType": "string"
        }
      },
      "parameters": [],
      "errorString": null,
      "user": "MetasysSysAgent",
      "signature": null,
      "classLevel": "auditClassesEnumSet.userActionAuditClass",
      "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
      "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
      "annotationsUrl": null,
      "self": "https://{hostname}/api/v4/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
    }
  },
  "effectivePermission": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "canDiscard": true
  }
}

  • activity.audit.annotate - An annotate audit event is sent when an annotation is added to an audit activity, providing the information for the annotated audit.

    Annotate Audit Payload Example 
    {
  "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
  "activity": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "itemReference": "{hostname}:{deviceHostname}",
    "objectName": "MS-NAE5510-3",
    "activityManagementStatus": "pending",
    "creationTime": "2021-02-16T16:21:10.23Z",
    "objectUrl": "https://{hostname}/api/v4/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
    "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
    "audit": {
      "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
      "status": null,
      "preData": null,
      "postData": {
        "item": "10.10.198.131",
        "schema": {
          "type": "string",
          "metasysType": "string"
        }
      },
      "parameters": [],
      "errorString": null,
      "user": "MetasysSysAgent",
      "signature": null,
      "classLevel": "auditClassesEnumSet.userActionAuditClass",
      "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
      "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
      "annotationsUrl": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v4/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
    }
  },
  "effectivePermission": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "canDiscard": true
  }
}

  • activity.audit.discard - An audit discard event is sent when the management status of an audit activity changes to discarded.

    Discard Audit Payload Example 
    {
  "subscriptionIds": ["7373cc85-37a5-4ad5-b703-6bc61968aa9a"],
  "activity": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "itemReference": "{hostname}:{deviceHostname}",
    "objectName": "MS-NAE5510-3",
    "activityManagementStatus": "discarded",
    "creationTime": "2021-02-16T16:21:10.23Z",
    "objectUrl": "https://{hostname}/api/v4/objects/CDAC85B9-726F-5677-9CBC-ADC77A14E79B",
    "objectId": "cdac85b9-726f-5677-9cbc-adc77a14e79b",
    "audit": {
      "actionType": "auditActionTypeEnumSet.subsystemAuditActionType",
      "status": null,
      "preData": null,
      "postData": {
        "item": "10.10.198.131",
        "schema": {
          "type": "string",
          "metasysType": "string"
        }
      },
      "parameters": [],
      "errorString": null,
      "user": "MetasysSysAgent",
      "signature": null,
      "classLevel": "auditClassesEnumSet.userActionAuditClass",
      "originApplication": "auditOriginAppEnumSet.systemSecurityAuditOriginApp",
      "description": "auditTrailStringsEnumSet.atstrSecurityUserLoginSuccessful",
      "annotationsUrl": "https://{hostname}/api/v4/alarms/6443a123-ddcd-47e7-9828-d872db6a7b4f/annotations",
      "self": "https://{hostname}/api/v4/audits/128d7db4-8ab6-4232-afe1-026fe06d267f"
    }
  },
  "effectivePermission": {
    "id": "128d7db4-8ab6-4232-afe1-026fe06d267f",
    "canDiscard": true
  }
}

Filter Behavior

Filters supplied to an activities request limit the results to activities for which the filters apply. When subscribing to an activities request that uses filters, the events received are also limited to the same filter criteria. Exceptions to this behavior occur when filtering on activity management status, such as for acknowledged or discarded activities. You receive an update whenever an activity management change occurs, regardless of filters, because the change can impact the original set of activities you subscribed to. For example, consider the following scenario:

  • You subscribe to acknowledged activities and receive all acknowledged activities, receiving updates for any acknowledged thereafter across the stream.
  • In this state, one of the activities in your original list is discarded by another user.

When this occurs, you receive an activity.alarm.discard message for the discarded activity even though your filters exclude activities that are discarded. This is necessary so that you can properly maintain the state of activities already received in your application.

List activities

Retrieves a collection of activities.

Authorizations:
Bearer-Authentication
query Parameters
activityType
Array of strings[ items <= 2 items ]
Items Enum: "alarm" "audit"
Example: activityType=alarm

Limit the activities returned to a specific type

includeDiscarded
boolean

Determines whether discarded activities will be included in the results or be the only type of activity in the results. Discarded activities are those for which the activityManagementStatus is discarded.

This parameter can produce 3 different types of results.

  • true - Return only discarded activities in the response.
  • false - Do not include any discarded activities in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded activities are returned.
continuationToken
string
Example: continuationToken=eyJhdWRpdCI6eyJpZCI6IjgOTQ2NjUzLTlmM...

Provide a token from a previous request to fetch the next set of results. Ignored for streaming subscriptions.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether activities which can be acknowledged are included in the results. When the value is true, activities which can be acknowledged will be included in the results. When false, activities which can be acknowledged will not be included in the results.

The use of this parameter implies a filter of activityType=alarm and the results will not include any audits.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether activities which can not be acknowledged are included in the results. When the value is true then the results will include activities which cannot be acknowledged. When the value is false then the results will not include activities which cannot be acknowledged.

The use of this parameter implies a filter of activityType=alarm and the results will not include any audits.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

originApplication
Array of strings
Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp
metasysEnum: auditOriginAppEnumSet

Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message.

The acceptable values for the elements of this parameter come from the auditOriginAppEnumSet enumeration. Only the long name of the origin application (for example, auditOriginAppEnumSet.deviceManagerAuditOriginApp instead of deviceManagerAuditOriginApp) is accepted. Find the definition of auditOriginAppEnumSet at the relative URL of /schemas/enums/auditOriginAppEnumSet.

See also:

classLevel
Array of strings
Example: classLevel=auditClassesEnumSet.userActionAuditClass
metasysEnum: auditClassesEnumSet

Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose.

The Enabled Audit Level attribute (attributeEnumSet.auditEnabledClasLev) determines which audit levels the system generates. Therefore, be aware that there will be no audits to return if the Enabled Audit Level attribute is set too low to generate audits at the desired class level in this filter. This attribute is set per device (for audits generated on that device).

The acceptable values for the elements of this parameter come from the auditClassesEnumSet enumeration. Only the long name of the class level (for example, auditClassesEnumSet.userActionAuditClass instead of userActionAuditClass) is accepted. Find the definition of auditClassesEnumSet at the relative URL of /schemas/enums/auditClassesEnumSet.

See also:

actionType
Array of strings
Example: actionType=auditActionTypeEnumSet.writeAuditActionType
metasysEnum: auditActionTypeEnumSet

Filter by list of action types. The action type property indicates the user or system action performed.

The acceptable values for the elements of this parameter come from the auditActionTypeEnumSet enumeration. Only the long name of the action type (for example, auditActionTypeEnumSet.writeAuditActionType instead of writeAuditActionType) is accepted. Find the definition of auditActionTypeEnumSet at the relative URL of /schemas/enums/auditActionTypeEnumSet.

See also:

user
Array of strings <= 100 items
Example: user=metasysuser

Filter by list of users. The user property indicates which user initiated the action being audited.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/activities?activityType=alarm&includeDiscarded=false&continuationToken=eyJhdWRpdCI6eyJpZCI6IjgOTQ2NjUzLTlmM...&sort=creationTime&startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&category=objectCategoryEnumSet.hvacCategory&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v4+json

The first 10 activities.

{}

Batch operations

Used to invoke multiple activity operations in a single HTTP request. In this version of the API, the only activity-related operations that can be used in a batch are listed below.

See also

Authorizations:
Bearer-Authentication
Request Body schema: application/json
method
required
string
Enum: "PATCH" "POST"

The HTTP method to use for each request.

required
Array of objects

A collection of entries that represent the operations to invoke.

Responses

Request samples

Content type
application/json
Example

A request to discard multiple activities (2 audits and 2 alarms). One audit request and one alarm request include annotation text and the other requests do not.

{}

Response samples

Content type
application/vnd.metasysapi.v4+json

This is an example response to a batch request. Two of the operations succeeded and two of them failed.

{
  • "responses": [
    ]
}

Delete activities subscription

Deletes a subscription to the activities resource.

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Responses

Request samples 

curl --request DELETE \
  --url https:///%7Bhostname%7D/api/v4/activities/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

alarms

Alarms alert users to potential problems identified by a Metasys system, for example high zone temperatures. Use alarms operations to get object alarms, network device alarms, single alarms, alarm collections, and alarm annotations. Acknowledge or discard alarms with the edit patch operation. Filter the results with the query parameters time, priority, type, category, acknowledgement, and page. Sort the results by creation time and priority.

Get alarms for an object

Retrieves a collection of alarms for the specified object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeDiscarded
boolean

Determines whether discarded alarms will be included in the results or be the only type of alarm in the results. Discarded alarms are those for which the activityManagementStatus is discarded. This parameter can produce 3 different types of results.

  • true - Return only discarded alarms in the response.
  • false - Do not include any discarded alarms in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether alarms which can be acknowledged are included in the results. When the value is true, alarms which can be acknowledged will be included in the results. When false, alarms which can be acknowledged will not be included in the results.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether alarms which can not be acknowledged are included in the results. When the value is true then the results will include alarms which cannot be acknowledged. When the value is false then the results will not include alarms which cannot be acknowledged.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

The first 10 alarms.

{}

Get alarms for a network device

Retrieves a collection of alarms for the specified network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeDiscarded
boolean

Determines whether discarded alarms will be included in the results or be the only type of alarm in the results. Discarded alarms are those for which the activityManagementStatus is discarded. This parameter can produce 3 different types of results.

  • true - Return only discarded alarms in the response.
  • false - Do not include any discarded alarms in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether alarms which can be acknowledged are included in the results. When the value is true, alarms which can be acknowledged will be included in the results. When false, alarms which can be acknowledged will not be included in the results.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether alarms which can not be acknowledged are included in the results. When the value is true then the results will include alarms which cannot be acknowledged. When the value is false then the results will not include alarms which cannot be acknowledged.

equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

The first 10 alarms.

{}

Get alarms Deprecated

Retrieves a collection of alarms.

Note: This operation is deprecated and may be removed in a future release. To retrieve alarms, consider using GET /activities?activityType=alarm instead. See List activities

Authorizations:
Bearer-Authentication
query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

priorityRange
string^\d+,\d+$
Example: priorityRange=0,255

Includes only results within the specified alarm priority range, from 0 to 255 inclusive.

type
Array of strings[ items <= 100 items ]
Example: type=alarmValueEnumSet.avHighLimit
metasysEnum: alarmValueEnumSet

Limits the alarms returned to specified types.

The acceptable values for the elements of this parameter come from the alarmValueEnumSet enumeration. Only the long name of the alarm value (for example, alarmValueEnumSet.avHighLimit instead of avHighLimit) is accepted. Find the definition of alarmValueEnumSet at the relative URL of /schemas/enums/alarmValueEnumSet.

See also:

includeAcknowledged
boolean

Determines whether acknowledged alarms will be included in the results or be the only type of alarm in the results. Acknowledged alarms are those which have an acknowledgedTime value set.

This parameter can produce 3 different types of results.

  • true - Return only acknowledged alarms in the response.
  • false - Do not include any acknowledged alarms in the response.
  • missing - (default) Acknowledged status is ignored; both acknowledged and non-acknowledged alarms are returned.
includeDiscarded
boolean

Determines whether discarded alarms will be included in the results or be the only type of alarm in the results. Discarded alarms are those for which the activityManagementStatus is discarded. This parameter can produce 3 different types of results.

  • true - Return only discarded alarms in the response.
  • false - Do not include any discarded alarms in the response.
  • missing - (default) Discarded status is ignored; both discarded and non-discarded alarms are returned.
includeAcknowledgementRequired
boolean
Default: true
Example: includeAcknowledgementRequired=true

Determines whether alarms which can be acknowledged are included in the results. When the value is true, alarms which can be acknowledged will be included in the results. When false, alarms which can be acknowledged will not be included in the results.

includeAcknowledgementNotRequired
boolean
Default: true
Example: includeAcknowledgementNotRequired=true

Determines whether alarms which can not be acknowledged are included in the results. When the value is true then the results will include alarms which cannot be acknowledged. When the value is false then the results will not include alarms which cannot be acknowledged.

equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

category
Array of strings
Example: category=objectCategoryEnumSet.hvacCategory
metasysEnum: objectCategoryEnumSet

The authorization category of the requested activities.

The acceptable values for the elements of this parameter come from the objectCategoryEnumSet enumeration. Only the long name of the object category (for example, objectCategoryEnumSet.hvacCategory instead of hvacCategory) is accepted. Find the definition of objectCategoryEnumSet at the relative URL of /schemas/enums/objectCategoryEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "priority" "-priority"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/alarms?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&priorityRange=0%2C255&type=alarmValueEnumSet.avHighLimit&includeAcknowledged=false&includeDiscarded=false&includeAcknowledgementRequired=true&includeAcknowledgementNotRequired=true&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&category=objectCategoryEnumSet.hvacCategory&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

The first 10 alarms.

{}

Get an alarm

Retrieves the specified alarm.

Authorizations:
Bearer-Authentication
path Parameters
alarmId
required
string
Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5

The identifier of the alarm.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/alarms/4d0598d4-2836-4efd-84b8-6f39754b1fc5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

An alarm for an analog value object.

{}

Edit an alarm

Allows for acknowledging or discarding an alarm.

Authorizations:
Bearer-Authentication
path Parameters
alarmId
required
string
Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5

The identifier of the alarm.

Request Body schema: application/json
activityManagementStatus
required
string
Enum: "acknowledged" "discarded"

The new activity management status of the alarm.

The values of this property are described as follows:

  • acknowledged - The alarm has been recognized and viewed by a user. An alarm may only be acknowledged if activityManagementStatus is currently pending and isAckRequired is true.
  • discarded - The alarm has been acted upon and addressed by a user. Once an alarm is discarded, it cannot be changed to any other state.
annotationText
string or null

The annotation associated with the change of alarm state.

Responses

Request samples

Content type
application/json
Example
{
  • "activityManagementStatus": "acknowledged"
}

Get alarm annotations

Retrieves the collection of annotations available for the specified alarm.

Authorizations:
Bearer-Authentication
path Parameters
alarmId
required
string
Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5

The identifier of the alarm.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime" "user" "-user"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/alarms/4d0598d4-2836-4efd-84b8-6f39754b1fc5/annotations?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{}

Add alarm annotation (INTERNAL)

Adds an annotation to an alarm.

visibility: internal
Authorizations:
Bearer-Authentication
path Parameters
alarmId
required
string
Example: 4d0598d4-2836-4efd-84b8-6f39754b1fc5

The identifier of the alarm.

Request Body schema: application/json
text
required
string [ 1 .. 255 ] characters \S

The text of the annotation to create. This must not be null, empty, nor only whitespace. Additionally, any surrounding whitespace will be trimmed.

Responses

Request samples

Content type
application/json
{
  • "text": "Looks okay."
}

audits

How to retrieve, discard, and annotate audits.

Relationships

Audits have relationships to other resources in the system. Find information about the most important below.

  • objects

When users or the system affect objects in the Metasys system, such as analog inputs, multistate objects, or binary outputs, audits are generated. Those "acted upon" objects then relate to those audits. That relationship is returned as part of any audit response.

  • equipment instances

Equipment instance associations to audits build off of the objects association explanation. Each equipment instance can contain many points, such as Outdoor Air Temperature, Damper Position, or Zone Setpoint. Those points map to actual objects in Metasys, as noted above. When users or the system affect those objects, audits are generated. If an equipment instance's point is mapped to one of those affected objects the instance is then associated with that audit.

In short, an equipment instance contains points which map to Metasys objects which are affected by an audited action.

  • spaces

Space associations to audits build off of the equipment instance association explanation. Equipment instances can serve spaces, such as an Air Handler Unit (AHU) serving the floor of a building. Therefore, audits associated with a particular equipment instance are associated to the spaces they serve.

Get audits for an object

Retrieves a collection of audits for the specified object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

originApplication
Array of strings
Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp
metasysEnum: auditOriginAppEnumSet

Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message.

The acceptable values for the elements of this parameter come from the auditOriginAppEnumSet enumeration. Only the long name of the origin application (for example, auditOriginAppEnumSet.deviceManagerAuditOriginApp instead of deviceManagerAuditOriginApp) is accepted. Find the definition of auditOriginAppEnumSet at the relative URL of /schemas/enums/auditOriginAppEnumSet.

See also:

classLevel
Array of strings
Example: classLevel=auditClassesEnumSet.userActionAuditClass
metasysEnum: auditClassesEnumSet

Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose.

The Enabled Audit Level attribute (attributeEnumSet.auditEnabledClasLev) determines which audit levels the system generates. Therefore, be aware that there will be no audits to return if the Enabled Audit Level attribute is set too low to generate audits at the desired class level in this filter. This attribute is set per device (for audits generated on that device).

The acceptable values for the elements of this parameter come from the auditClassesEnumSet enumeration. Only the long name of the class level (for example, auditClassesEnumSet.userActionAuditClass instead of userActionAuditClass) is accepted. Find the definition of auditClassesEnumSet at the relative URL of /schemas/enums/auditClassesEnumSet.

See also:

actionType
Array of strings
Example: actionType=auditActionTypeEnumSet.writeAuditActionType
metasysEnum: auditActionTypeEnumSet

Filter by list of action types. The action type property indicates the user or system action performed.

The acceptable values for the elements of this parameter come from the auditActionTypeEnumSet enumeration. Only the long name of the action type (for example, auditActionTypeEnumSet.writeAuditActionType instead of writeAuditActionType) is accepted. Find the definition of auditActionTypeEnumSet at the relative URL of /schemas/enums/auditActionTypeEnumSet.

See also:

user
Array of strings <= 100 items
Example: user=metasysuser

Filter by list of users. The user property indicates which user initiated the action being audited.

includeDiscarded
boolean

Determines whether discarded audits will be included in the results.

  • true - Return only discarded audits in the response.
  • false - Do not include any discarded audits in the response.
  • missing - Discarded status is ignored; both discarded and non-discarded audits are returned.
equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/audits?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser&includeDiscarded=false&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&space=214f52d1-0c56-4a29-a690-abe5656d1647&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

Gets the first 10 audits.

{
  • "total": 400,
  • "next": "https://{hostname}/api/v4/objects/a68f10e5-da10-5b87-a96b-42a36e9919ae/audits?page=2&pageSize=10&sort=-creationtime",
  • "previous": null,
  • "items": [
    ],
  • "effectivePermissions": [
    ],
  • "self": "https://{hostname}/api/v4/audits?page=1&pageSize=10&sort=-creationtime"
}

Get audits Deprecated

Retrieves a collection of audits.

Note: This operation is deprecated and may be removed in a future release. To retrieve audits, consider using GET /activities?activityType=audit instead. See List activities

Authorizations:
Bearer-Authentication
query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

originApplication
Array of strings
Example: originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp
metasysEnum: auditOriginAppEnumSet

Filter by list of origin applications. The origin application property indicates which application in Metasys generated the audit message.

The acceptable values for the elements of this parameter come from the auditOriginAppEnumSet enumeration. Only the long name of the origin application (for example, auditOriginAppEnumSet.deviceManagerAuditOriginApp instead of deviceManagerAuditOriginApp) is accepted. Find the definition of auditOriginAppEnumSet at the relative URL of /schemas/enums/auditOriginAppEnumSet.

See also:

classLevel
Array of strings
Example: classLevel=auditClassesEnumSet.userActionAuditClass
metasysEnum: auditClassesEnumSet

Filter by list of class levels. The class level of an audit indicates the class or family the audit belongs to. Typically, each level of audit provides additional detail about the system, with Diagnostic audits being the most verbose.

The Enabled Audit Level attribute (attributeEnumSet.auditEnabledClasLev) determines which audit levels the system generates. Therefore, be aware that there will be no audits to return if the Enabled Audit Level attribute is set too low to generate audits at the desired class level in this filter. This attribute is set per device (for audits generated on that device).

The acceptable values for the elements of this parameter come from the auditClassesEnumSet enumeration. Only the long name of the class level (for example, auditClassesEnumSet.userActionAuditClass instead of userActionAuditClass) is accepted. Find the definition of auditClassesEnumSet at the relative URL of /schemas/enums/auditClassesEnumSet.

See also:

actionType
Array of strings
Example: actionType=auditActionTypeEnumSet.writeAuditActionType
metasysEnum: auditActionTypeEnumSet

Filter by list of action types. The action type property indicates the user or system action performed.

The acceptable values for the elements of this parameter come from the auditActionTypeEnumSet enumeration. Only the long name of the action type (for example, auditActionTypeEnumSet.writeAuditActionType instead of writeAuditActionType) is accepted. Find the definition of auditActionTypeEnumSet at the relative URL of /schemas/enums/auditActionTypeEnumSet.

See also:

user
Array of strings <= 100 items
Example: user=metasysuser

Filter by list of users. The user property indicates which user initiated the action being audited.

includeDiscarded
boolean

Determines whether discarded audits will be included in the results.

  • true - Return only discarded audits in the response.
  • false - Do not include any discarded audits in the response.
  • missing - Discarded status is ignored; both discarded and non-discarded audits are returned.
equipment
Array of strings <= 100 items
Example: equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398

Filter by list of equipment identifiers.

object
Array of strings <= 100 items
Example: object=06d77c63-6357-467a-a306-5e1ab3eb3aa7

Filter by list of object identifiers.

space
Array of strings <= 100 items
Example: space=214f52d1-0c56-4a29-a690-abe5656d1647

Filter by list of space identifiers.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/audits?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&originApplication=auditOriginAppEnumSet.deviceManagerAuditOriginApp&classLevel=auditClassesEnumSet.userActionAuditClass&actionType=auditActionTypeEnumSet.writeAuditActionType&user=metasysuser&includeDiscarded=false&equipment=b7ed8b3e-cb95-410d-aaa7-37158852c398&object=06d77c63-6357-467a-a306-5e1ab3eb3aa7&space=214f52d1-0c56-4a29-a690-abe5656d1647&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

Gets the first 10 audits.

{
  • "total": 400,
  • "next": "https://{hostname}/api/v4/audits?page=2&pageSize=10&sort=-creationtime",
  • "previous": null,
  • "items": [
    ],
  • "effectivePermissions": [
    ],
  • "self": "https://{hostname}/api/v4/audits?page=1&pageSize=10&sort=-creationtime"
}

Get an audit

Retrieves the specific audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/audits/4990ee27-7a0a-4b2b-9b27-279e3f1a060c \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

An audit for an analog value object.

{
  • "id": "6c6ae3dd-c514-423d-bd22-0b48678c5384",
  • "creationTime": "2021-12-10T21:05:53Z",
  • "actionType": "auditActionTypeEnumSet.commandAuditActionType",
  • "activityManagementStatus": "pending",
  • "status": "statusEnumSet.ok",
  • "spaces": [ ],
  • "equipment": [ ],
  • "preData": {
    },
  • "postData": null,
  • "parameters": [
    ],
  • "errorString": null,
  • "user": null,
  • "signature": null,
  • "objectUrl": "https://{hostname}/api/v4/objects/283fd3ad-ab1c-5849-8bdb-d635c5c274d9",
  • "self": "https://{hostname}/api/v4/audits/6c6ae3dd-c514-423d-bd22-0b48678c5384",
  • "itemReference": "{hostname}:{deviceHostname}/AV1",
  • "objectName": "Interlock1/AV1",
  • "classLevel": "auditClassesEnumSet.applicationAuditClass",
  • "originApplication": "auditOriginAppEnumSet.interlockAuditOriginApp",
  • "description": "commandIdEnumSet.adjustCommand"
}

Edit an audit

Allows for discarding an audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

Request Body schema: application/json
activityManagementStatus
required
string
Value: "discarded"

The new activity management status of the audit.

The only accepted value of this property is discarded because it is the only valid activity management state transition for an audit. Once an audit is discarded, it cannot be changed to any other state.

annotationText
string or null

The annotation to associate with the change of audit state.

Responses

Request samples

Content type
application/json
{
  • "activityManagementStatus": "discarded"
}

Get audit annotations

Retrieves the collection of annotations available for the specified audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "creationTime"
Enum: "creationTime" "-creationTime"
Example: sort=creationTime

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/audits/4990ee27-7a0a-4b2b-9b27-279e3f1a060c/annotations?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=100&sort=creationTime' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{}

Add audit annotation

Adds an annotation to an audit.

Authorizations:
Bearer-Authentication
path Parameters
auditId
required
string
Example: 4990ee27-7a0a-4b2b-9b27-279e3f1a060c

The identifier of the audit.

Request Body schema: application/json
text
required
string [ 1 .. 255 ] characters \S

The text of the annotation to create. This must not be null, empty, nor only whitespace. Additionally, any surrounding whitespace will be trimmed.

Responses

Request samples

Content type
application/json
{
  • "text": "Looks okay."
}

List audit users

Retrieves a list of unique usernames from all users present in a currently stored audit. The provided usernames may or may not reflect known users of the current system, but were known when the system recorded an audit for them.

Authorizations:
Bearer-Authentication

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/audits/users \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{}

Get audit counts (PRIVATE)

Gets counts of audits in specified time intervals for a given time period grouped by audit string ids (optionally grouped by specified time interval).

Authorizations:
Bearer-Authentication
query Parameters
auditActions
Array of integers
Example: auditActions=41,42,107,150

Filter by audit strings. auditTrailStringsEnumSet.

The values for this property come from the auditTrailStringsEnumSet.

Find the definition of auditTrailStringsEnumSet at the relative URL of /schemas/enums/auditTrailStringsEnumSet.

Note: This parameter does not follow the standard convention of using symbolic names. You must provide the integer identifier of the members of the set you wish to filter by.

See also:

startTime
required
string <date-time>
Example: startTime=2022-07-21T10:00:00-05:00

Only include results generated on or after this date-time.

endTime
required
string <date-time>
Example: endTime=2022-07-22T09:08:59-05:00

Only include results generated on or before this date-time.

timeInterval
string
Default: "None"
Enum: "None" "Hour" "Day" "Week" "Month"
Example: timeInterval=Hour

A time interval in which audit counts will be grouped by.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/audits/counts?auditActions=41%2C42%2C107%2C150&startTime=2022-07-21T10%3A00%3A00-05%3A00&endTime=2022-07-22T09%3A08%3A59-05%3A00&timeInterval=Hour' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example
[
  • {
    },
  • {
    }
]

authentication

Operations to get and refresh an access token.

Request access token

Use this to request an access token that can be used for authentication on other API calls.

Request Body schema: application/json

Used to supply credentials for login.

username
string

The user name of an account. This can either be a local Metasys account, or an Active Directory account that has been granted access to Metasys. When using an Active Directory account, the value should be in the format {name}@{domain} (for example, jane-doe@mycorp.com).

Note: Only accounts with an Access Type of API can be used to request a token from the REST API.

password
string

The corresponding password of a Metasys account.

Responses

Request samples

Content type
application/json
Example
{
  • "username": "jane-doe",
  • "password": "strongPassword"
}

Response samples

Content type
application/vnd.metasysapi.v4+json

The result includes the access token needed to make requests. (The token in this example has been truncated.)

{
  • "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
  • "expires": "2021-04-22T00:12:18Z"
}

Refresh a token

Use this operation to request a new token before the previous one expires. Note: If the expiration time of the access token is greater than 60 minutes from issue, disregard and refresh before 60 minutes to prevent session expiration. The next version of the API will provide the correct expiration time.

Authorizations:
Bearer-Authentication

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/refreshToken \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

The result includes the access token needed to make requests. (The token in this example has been truncated.)

{
  • "accessToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1...",
  • "expires": "2021-04-22T00:12:18Z"
}

certificates

Operations related to certificates and signing requests of network devices

Read a certificate signing request (PRIVATE)

Retrieve the binary CSR data for a single device. A successful (200) response provides the CSR in a PEM format.

Note: This endpoint is intended to support application/vnd.metasysapi.v4+json and application/octet-stream MIME types via the Accept header however neither of these are currently supported. Only application/pkcs10 is supported even though it shouldn't be.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

header Parameters
If-None-Match
string
Example: DrIITJxrrFDVYbFrmM41X6xj/v+HlD/QgWuvNeIPCvM=

A previous ETag header value. If the current state of the resource does not match this, then the current resource will be returned. If the current state of the resource does match this value, then the current resource will not be returned and the response will be a 304 (Not Modified).

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/signingRequests/bacnet \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'If-None-Match: DrIITJxrrFDVYbFrmM41X6xj/v+HlD/QgWuvNeIPCvM='

Response samples

Content type

A certificate signing request in PEM format meant for a raw output (a MIME type of application/octet-stream).

-----BEGIN CERTIFICATE REQUEST-----
MIIBlTCCARwCAQIwgZwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJXSTESMBAGA1UE
BwwJTWlsd2F1a2VlMRkwFwYDVQQKDBBKb2huc29uIENvbnRyb2xzMREwDwYDVQQL
DAhDb250cm9sczEYMBYGA1UEAwwPTUFDMDI0MkFDMTUxNzA2MSQwIgYJKoZIhvcN
AQkBFhVqYWNvYi5wLmhpY2tzQGpjaS5jb20wdjAQBgcqhkjOPQIBBgUrgQQAIgNi
AASv3V9GGmXQqNmTCKIZPy4unQBGPDYG6RzqybRrJO6ZSVTm31y1XYuvFIE0u+I3
NrtpR0DPDCvfDlecQkEpkgB5roIijDh7/ZEKDwQgvc8pvxWVzCv7OQw4OoCK1bd8
SXOgADAKBggqhkjOPQQDAgNnADBkAjBoC8P9g/2r9yS1MR9H4iv/f3uvbzP8PQd3
4PJdATJjZsHWVml1E42DEK5ejQDl6rICMFLNL5Mwf029d9v+/X2UvrZ12TJDC8nx
2ZrcTdE6zw5cyxVwR9xyJ8YqU35iqvsTmA==
-----END CERTIFICATE REQUEST-----

Create certificate signing request (PRIVATE)

Create a new certificate signing request (CSR) for the specified device and CSR parameters. A successful (201) response provides the CSR in a PEM format.

Note: This endpoint is intended to support application/vnd.metasysapi.v4+json and application/octet-stream MIME types via the Accept header however neither of these are currently supported. Only application/pkcs10 is supported even though it shouldn't be.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

Request Body schema: application/json
emailAddress
required
string <email> [ 1 .. 63 ] characters
orgName
required
string [ 1 .. 63 ] characters
orgUnitName
required
string [ 1 .. 63 ] characters
city
required
string [ 1 .. 63 ] characters
stateProvince
required
string [ 1 .. 63 ] characters
country
required
string = 2 characters
domainName
string or null [ 1 .. 47 ] characters

Responses

Request samples

Content type
application/json
{
  • "city": "Milwaukee",
  • "country": "US",
  • "emailAddress": "noreply@jci.com",
  • "orgName": "Johnson Controls",
  • "orgUnitName": "BAS",
  • "stateProvince": "WI",
  • "domainName": "jci.com"
}

Response samples

Content type

A certificate signing request in PEM format meant for a raw output (a MIME type of application/octet-stream).

-----BEGIN CERTIFICATE REQUEST-----
MIIBlTCCARwCAQIwgZwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJXSTESMBAGA1UE
BwwJTWlsd2F1a2VlMRkwFwYDVQQKDBBKb2huc29uIENvbnRyb2xzMREwDwYDVQQL
DAhDb250cm9sczEYMBYGA1UEAwwPTUFDMDI0MkFDMTUxNzA2MSQwIgYJKoZIhvcN
AQkBFhVqYWNvYi5wLmhpY2tzQGpjaS5jb20wdjAQBgcqhkjOPQIBBgUrgQQAIgNi
AASv3V9GGmXQqNmTCKIZPy4unQBGPDYG6RzqybRrJO6ZSVTm31y1XYuvFIE0u+I3
NrtpR0DPDCvfDlecQkEpkgB5roIijDh7/ZEKDwQgvc8pvxWVzCv7OQw4OoCK1bd8
SXOgADAKBggqhkjOPQQDAgNnADBkAjBoC8P9g/2r9yS1MR9H4iv/f3uvbzP8PQd3
4PJdATJjZsHWVml1E42DEK5ejQDl6rICMFLNL5Mwf029d9v+/X2UvrZ12TJDC8nx
2ZrcTdE6zw5cyxVwR9xyJ8YqU35iqvsTmA==
-----END CERTIFICATE REQUEST-----

Replace certificate signing request (PRIVATE)

Replace the certificate signing request (CSR) for the specified device and CSR parameters. A successful (200) response provides the CSR in a PEM format.

Note: This endpoint is intended to support application/vnd.metasysapi.v4+json and application/octet-stream MIME types via the Accept header however neither of these are currently supported. Only application/pkcs10 is supported even though it shouldn't be.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

header Parameters
If-Match
required
string
Example: 33a64df551425fcc55e4d42a148795d9f25f89d4

A previous ETag header value. If the current state of the resource does not match this value, then the operation will fail. If the current state of the resource does match this value, then the operation will continue.

Request Body schema: application/json
emailAddress
required
string <email> [ 1 .. 63 ] characters
orgName
required
string [ 1 .. 63 ] characters
orgUnitName
required
string [ 1 .. 63 ] characters
city
required
string [ 1 .. 63 ] characters
stateProvince
required
string [ 1 .. 63 ] characters
country
required
string = 2 characters
domainName
string or null [ 1 .. 47 ] characters

Responses

Request samples

Content type
application/json
{
  • "city": "Milwaukee",
  • "country": "US",
  • "emailAddress": "noreply@jci.com",
  • "orgName": "Johnson Controls",
  • "orgUnitName": "BAS",
  • "stateProvince": "WI",
  • "domainName": "jci.com"
}

Response samples

Content type

A certificate signing request in PEM format meant for a raw output (a MIME type of application/octet-stream).

-----BEGIN CERTIFICATE REQUEST-----
MIIBlTCCARwCAQIwgZwxCzAJBgNVBAYTAlVTMQswCQYDVQQIDAJXSTESMBAGA1UE
BwwJTWlsd2F1a2VlMRkwFwYDVQQKDBBKb2huc29uIENvbnRyb2xzMREwDwYDVQQL
DAhDb250cm9sczEYMBYGA1UEAwwPTUFDMDI0MkFDMTUxNzA2MSQwIgYJKoZIhvcN
AQkBFhVqYWNvYi5wLmhpY2tzQGpjaS5jb20wdjAQBgcqhkjOPQIBBgUrgQQAIgNi
AASv3V9GGmXQqNmTCKIZPy4unQBGPDYG6RzqybRrJO6ZSVTm31y1XYuvFIE0u+I3
NrtpR0DPDCvfDlecQkEpkgB5roIijDh7/ZEKDwQgvc8pvxWVzCv7OQw4OoCK1bd8
SXOgADAKBggqhkjOPQQDAgNnADBkAjBoC8P9g/2r9yS1MR9H4iv/f3uvbzP8PQd3
4PJdATJjZsHWVml1E42DEK5ejQDl6rICMFLNL5Mwf029d9v+/X2UvrZ12TJDC8nx
2ZrcTdE6zw5cyxVwR9xyJ8YqU35iqvsTmA==
-----END CERTIFICATE REQUEST-----

Delete certificate signing request (PRIVATE)

Clear any existing certificate signing request (CSR) for the specified device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

header Parameters
If-Match
required
string
Example: 33a64df551425fcc55e4d42a148795d9f25f89d4

A previous ETag header value. If the current state of the resource does not match this value, then the operation will fail. If the current state of the resource does match this value, then the operation will continue.

Responses

Request samples 

curl --request DELETE \
  --url https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/signingRequests/bacnet \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'If-Match: 33a64df551425fcc55e4d42a148795d9f25f89d4'

Response samples

Content type
application/vnd.metasysapi.v4+json
{
  • "statusName": "string",
  • "message": "string",
  • "details": { },
  • "innerError": { },
  • "innerErrors": [
    ]
}

Read BACnet/SC certificate (PRIVATE)

Retrieve the raw and/or structured certificate data for a single device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
flatten
boolean
Default: true
Example: flatten=true

Return the certificates as a flat list or as nested trees. When nested, the result items will have an items array property that contains the child certificates.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/certificates/bacnet?flatten=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

Certificate details as a list. Note that JSON must encode new lines (\n) for the raw property.

{
  • "self": "https://{hostname}/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/certificates/bacnet?flatten=true",
  • "items": [
    ]
}

Write BACnet/SC certificate (PRIVATE)

Write the raw certificate data for a single device. The data may be a single operational certificate or the entire chain.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

Request Body schema: application/octet-stream
string <binary> (rawCertificate)

Responses

Request samples

Content type
application/octet-stream

A certificate in PEM format.

-----BEGIN CERTIFICATE-----
MIICJjCCAcugAwIBAgIJALlDHY8rFJaRMAoGCCqGSM49BAMCMBoxGDAWBgNVBAMT
D01ldGFzeXMgVGVzdCBDQTAeFw0yMTA0MTkyMjA2MzdaFw0yMjAzMzAxOTQ1MTBa
MH4xHzAdBgkqhkiG9w0BCQEWEHRlc3RAdGVzdEFsbC5jb20xGDAWBgNVBAMTD01B
QzAyNDI3MDM1QUM2RDELMAkGA1UECxMCQkUxDDAKBgNVBAoTA0pDSTEMMAoGA1UE
BxMDTUtFMQswCQYDVQQIEwJXSTELMAkGA1UEBhMCVVMwdjAQBgcqhkjOPQIBBgUr
gQQAIgNiAARei12VLrNFW9ThXWbuP9jjgqumm+qRbYmjRr2Eft09gzcn9fSZyr7g
pmUZVsTeEbzzkAJDDFVobQ4iis5iXD8iAs/h4DkFc5eoXmS5hWGL3n5VPLfE1hCB
D6HZCVGmd/6jeTB3MAkGA1UdEwQCMAAwCwYDVR0PBAQDAgWgMB0GA1UdJQQWMBQG
CCsGAQUFBwMBBggrBgEFBQcDAjAdBgNVHQ4EFgQULuIeIdZBqqIwQvIP4T/RKpWD
GoUwHwYDVR0jBBgwFoAUQTHU+UodcSQ+Yk/8IEaPAjRA+nowCgYIKoZIzj0EAwID
SQAwRgIhAOBqzqlMJtoTvQxH0qx1s6oVY1NvsyXthO9SZlwlYEkeAiEAwyU0/jgU
NaHD0eqyywHZxyQto1vTscCbTJZIuFOVGnk=
-----END CERTIFICATE-----

Response samples

Content type
application/vnd.metasysapi.v4+json
{
  • "statusName": "string",
  • "message": "string",
  • "details": { },
  • "innerError": { },
  • "innerErrors": [
    ]
}

Delete BACnet/SC certificate (PRIVATE)

Delete the certificate(s) for a single device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
loose
boolean
Default: true
Example: loose=true

If true, indicates that all issuer certificates which are not the authority of the currently active operational certificate should be deleted.

Note: Only true is currently supported.

Responses

Request samples 

curl --request DELETE \
  --url 'https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/certificates/bacnet?loose=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{
  • "statusName": "string",
  • "message": "string",
  • "details": { },
  • "innerError": { },
  • "innerErrors": [
    ]
}

Import BACnet/SC certificates (PRIVATE)

Write a collection of raw certificate data to the devices associated to the included certificates.

Authorizations:
Bearer-Authentication
Request Body schema: application/zip

A ZIP file which must contain 1 or more operational certificates and their issuer certificate(s). The issuer certificate(s) may be a separate file or included with each operational certificate (known as a PKCS #7 file).

string <binary>

Responses

Request samples 

curl --request POST \
  --url https:///%7Bhostname%7D/api/v4/networkDevices/certificates/bacnet \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

Import BACnet/SC certificates success response

[
  • {
    },
  • {
    },
  • {
    }
]

controls

Operations on control objects.

Diagrams

Some controls may have a visual representation known as a diagram. While a diagram is a visual representation, it is more importantly the means by which control logic is defined for some types of controls.

A diagram contains 3 general elements - blocks, ports, and connections.

A block generally represents some primitive function, such as an add operation. Most blocks work upon some number of input ports and provide the result via output ports. Blocks may have additional configuration to them as well.

The ports of blocks can be connected via connections to pass values from a source to a destination.

Block Schemas

Every block in a diagram is defined by a schema. A schema defines what the available properties and ports are available on a block. The properties and ports have associated metadata to define value types and value constraints.

A block schema is a JSON Schema, with some custom keywords:

  • sequenceProperties - indicates that all properties defined under it should be generated from a sequence of integer values. Every property name should be a format string which includes {n} as a placeholder to where the sequence number is populated. The source of the sequence numbering is defined by a countSource property, which defines how many properties are currently defined in the instance data that follow a templated sequence. This value should resolve to a property of the block. The schema of the countSource property should always be of type "integer", have a non-negative minimum, and have a maximum.
  • everything from the Object Developers Guide

Diagram Streaming Events

Diagrams may be subscribed to for streaming events by a client. A subscription is established by providing a METASYS-SUBSCRIBE header with the GET operation of a diagram.

See also:

To subscribe to a diagram use the Get diagram operation and include a METASYS-SUBSCRIBE header. The value of this header should be the stream id you received when you opened a stream.

Here are the types of events sent by the diagram subscription along with example data payloads for each.

  • diagram.subscription.established - Indicates when a subscription has been established for the diagram.

    Example Data Payload 
    {
  "id": "d7861b6a-d563-5521-a746-a68519cb7651",
  "subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"],
  "message": "Live value subscription successful"
}

  • diagram.subscription.cancelled - Indicates when a subscription has been cancelled for the diagram.

    Example Data Payload 
    {
  "id": "d7861b6a-d563-5521-a746-a68519cb7651",
  "subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
  "message": "Live value subscription cancelled"
}

  • diagram.values.update - Indicates a change in value of blocks or ports within the diagram. The first occurrence of this event will include all values in the diagram. Subsequent occurrences will only include values that changed from the previous occurrence.

    Example Data Payload 
    {
  "id": "d7861b6a-d563-5521-a746-a68519cb7651",
  "subscriptionIds": ["c569a157-7315-4f32-bc8f-11607f075660"],
  "items": [
    ["8", 2.0],
    ["9", 2.0, { "reliability": "reliabilityEnumSet.writeError" }]
  ]
}

    Each entry in items is a tuple of 2 or 3 values:

    • The first value is the identifier of the diagram entity (a diagram connection). This directly maps to the id property of the diagram entity.
    • The second value is the current value of the diagram entity. The type of this value could be a number, a string (in the case of an enumeration value), or null.
    • The third value is optional and represents any non-normal condition of the current value.

    The first diagram.values.update event payload for a new subscription of a diagram will contain all current values of entities in the diagram. Subsequent events will only contain values that changed from the previous event.

  • diagram.error - Indicates an error occurred during cancelling a subscription.

    Example Data Payload 
    {
  "subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
  "message": "Error while cancelling subscription"
}

  • diagram.heartbeat - Indicates that the logic service is alive.

    Example Data Payload 
    "ping from logic service @2021-08-04T16:03:23.3771485Z"

  • diagram.update - Indicates a change in the structure of the diagram. This event will cause the subscription to be cancelled.

    Example Data Payload 
    {
  "id": "d7861b6a-d563-5521-a746-a68519cb7651",
  "subscriptionIds": ["b287344d-2d57-45c1-a9f2-1ec954a36984"],
  "message": "The diagram has been updated.. Please refresh. Current subscription will be cancelled automatically."
}

Relationship to Objects

An instance of a control is really an instance of an object available at the relative URL of /objects/{objectId}. As a control, the representation of the object is more aligned with control logic in an abstracted manner rather than a more primitive and more complex representation.

Get diagram (INTERNAL)

Retrieves the diagram of the specified control instance.

If the METASYS-SUBSCRIBE header is provided, then an event subscription will be created which will include the events described in Diagrams

Authorizations:
Bearer-Authentication
path Parameters
controlId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the control.

query Parameters
includeSchema
boolean
Default: false

Indicates whether the schema of the diagram should also be returned.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/controls/5a22812f-ec51-4c11-ab4a-fc986f94f008/diagram?includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

Shows the results of a diagram with no blocks or connections.

{}

Replace diagram (INTERNAL)

Replaces the diagram of the specified control instance.

Possible Errors

There are a variety of errors that are possible when attempting to update a diagram. Every known error that can be determined will be communicated in a response. The error response is hierarchical such that the top-most errors describe generalized issues while inner-most errors describe specific issues. Each error is intended to be self-descriptive with accompanying details.

  • api.diagram:error.saveFailed

    The save failed. innerError or innerErrors will have more information

  • api.diagram:error.schemaFailure

    The payload did not validate against the schema.

  • api.diagram:error.diagramSchemaFailure

    The diagram did not validate against the schema.

  • api.diagram:error.invalidSchemaUrl

    A block's schema URL is invalid or doesn't reference a known block type.

  • api.diagram:error.blockSchemaFailure

    A block did not validate against its schema.

  • api.diagram:error.connectionSchemaFailure

    A connection did not validate against its schema.

  • api.diagram:error.unboundReferences

    The configured object reference for an Input Reference or Output Reference could not be resolved.

  • enum.core:statusEnumSet.writeAccessDeniedSecurity

    The user is not authorized to modify the diagram.

  • api.diagram:error.unauthorizedExistingDiagram

    The user is not authorized to modify the existing diagram.

  • api.diagram:error.unauthorizedRequestDiagram

    The user is not authorized to control some references in the new diagram.

  • api.diagram:error.duplicateId

    The same id is defined multiple times in the diagram.

  • api.diagram:error.circularLogic

    An unsupported circular loop has been defined in the diagram.

  • api.diagram:error.ioAttributes

    A general wrapper for any errors related to Input Attributes and Output Attributes.

  • api.diagram:error.ioThresholdExceeded

    The diagram contains more than the maximum allowed inputs or outputs.

  • api.diagram:error.duplicateIOBlockName

    The diagram contains duplicate Input Attribute and Output Attribute names.

  • api.diagram:error.duplicateIOAttribute

    The diagram contains duplicate Input Attribute and Output Attribute identifiers.

  • api.diagram:error.connection

    A general wrapper for any errors related to a connection.

  • api.diagram:error.portDoesNotExist

    The port referenced by a connection's source or destination is not defined.

  • api.diagram:error.portsCannotBeFromSameBlock

    A connection's source and destination cannot be from the same block.

  • api.diagram:error.delayConnectedToOutputTypeBlock

    A Delay block should not be connected to an Output Reference or Output Attribute.

  • api.diagram:error.priorityNotSupported

    A connection does not support priority when connected to anything other than Output Reference.

  • api.diagram:error.portDirectionInvalidForConnectionEndpoint

    The source of a connection cannot be an input port of a block and the destination of a connection cannot be an output port of a block.

  • api.diagram:error.block

    A general wrapper for any errors related to a block.

  • api.diagram:error.invalidEnum

    An enumeration value is not valid.

  • api.diagram:error.duplicatePortInSubSystem

    A System block cannot define a port as both being an input and an output.

  • api.diagram:error.portDoesNotExistInSubSystem

    A System block exposes a port which is not defined.

  • api.diagram:error.inPortIsNotWritableInSubSystem

    A System block exposes a input port which is not writable.

  • api.diagram:error.limitsCountMismatchInSequencer

    A Sequencer block doesn't have the same number of make limit values as break limit values.

  • api.diagram:error.limitsDoesNotMatchOutputsInSequencer

    A Sequencer block must have the same number of make & break limit values as the number of outputs. If proactive is true, then the expected count of limit values should be one less than the number of outputs.

  • api.diagram:error.limitsNotInAscendingOrderInSequencer

    A Sequencer block must have make & break limit values in ascending order.

  • api.diagram:error.breakIsGreaterThanMakeInSequencer

    A Sequencer block must have break limits which are less than their corresponding make limit of the same stage.

  • api.diagram:error.makeIsGreaterThanBreakInSequencer

    A Sequencer block must have make limits which are less than the break limit of the previous stage.

  • api.diagram:error.duplicateModeSelectionInMux

    A Multiplexor (MUX) block cannot use the same mode enumeration value multiple times.

Authorizations:
Bearer-Authentication
path Parameters
controlId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the control.

Request Body schema: application/json

The desired blocks and connections of the diagram. This is the same structure as the item property from the GET /diagram response.

required
object (Diagram)

A set of blocks and connections which make up an instance of programmable control logic.

Responses

Request samples

Content type
application/json
Example

A diagram with no blocks or connections.

{
  • "item": {
    }
}

Response samples

Content type
application/vnd.metasysapi.v4+json

Shows the response of a replace diagram request which had no item property.

{
  • "statusName": "api.diagram:error.saveFailed",
  • "message": "Diagram save failed. Please see innerError(s) for more information.",
  • "innerError": {
    }
}

Delete control subscription (INTERNAL)

Deletes a subscription to a control resource.

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Responses

Request samples 

curl --request DELETE \
  --url https:///%7Bhostname%7D/api/v4/controls/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Get palette (INTERNAL)

Retrieves a palette, which defines the available types of blocks available to diagramming.

Authorizations:
Bearer-Authentication
path Parameters
paletteId
required
string
Example: 01443cbc-d65e-4666-85d5-484a3b1f4f21

The identifier of the palette.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/controls/palettes/01443cbc-d65e-4666-85d5-484a3b1f4f21 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

An LCT palette (this is only a partial example).

{}

Get palette block (INTERNAL)

Retrieves the schema for a specific block type.

Authorizations:
Bearer-Authentication
path Parameters
paletteId
required
string
Example: 01443cbc-d65e-4666-85d5-484a3b1f4f21

The identifier of the palette.

blockDefinitionId
required
string
Examples:
  • text - Text
  • system-6441be80-52c2-4e40-ae60-655f3319c435 - LCT Sub-System

The ID of the block definition to get the schema for. The ID is the last portion of the schemaUrl and $id properties of a block definition.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/controls/palettes/01443cbc-d65e-4666-85d5-484a3b1f4f21/text \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

The Text Block definition on the LCT palette.

{
  • "$schema": "http://json-schema.org/draft-07/schema#",
  • "$id": "https://{hostname}/api/v4/controls/palettes/01443cbc-d65e-4666-85d5-484a3b1f4f21/text",
  • "title": "Text",
  • "description": "The schema for a text block instance",
  • "type": "object",
  • "properties": {
    },
  • "required": [
    ],
  • "additionalProperties": false,
  • "views": [
    ]
}

enumerations

Operations on enumerations

List enumerations (INTERNAL)

Enumerations are an important data type used by Metasys®. A single enumeration is used to define a set of values a property can have and each value includes a localized string to describe itself.

query Parameters
enumType
string
Default: "all"
Enum: "all" "twoState" "multiState" "custom"
Examples:
  • enumType=all - Return all
  • enumType=twoState - Return two-state only
  • enumType=multiState - Return multi-state only
  • enumType=custom - Return custom only

The type of enumerations to return.

minNumberOfStates
integer
Example: minNumberOfStates=4

Filter the result to include only those multi-state and custom enumerations with at least the specified minNumberOfStates. This parameter is ignored if enumType is not specified as custom or multiState. Note: For various reasons, some multi-state enums have more or less members than their defined number of states.

includePermissions
boolean
Default: false

Include effective permissions for the client with respect to enumerations.

header Parameters
Accept-Language
Array of strings
Example: en-US, de-De

The language to use for display text of enumeration name and members. If no language is specified the client's default language as specified in their user profile will be used.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/enumerations?enumType=all&minNumberOfStates=4&includePermissions=false' \
  --header 'Accept-Language: en-US, de-De'

Response samples

Content type
application/vnd.metasysapi.v4+json
{}

Create an enumeration (INTERNAL)

Create a custom enumeration with members of your choice

Authorizations:
Bearer-Authentication
Request Body schema: application/json

New enumeration

required
object

An enumeration

Responses

Request samples

Content type
application/json
{
  • "item": {
    }
}

Response samples

Content type
application/vnd.metasysapi.v4+json
{
  • "item": {
    }
}

Get an enumeration (INTERNAL)

Get an enumeration

path Parameters
id
required
string
Examples:
  • writePriorityEnumSet - The Write Priority enumeration
  • displayPrecisionEnumSet - The Display Precision enumeration
  • enumerationSetNamesEnumSet - The Enumeration Set Names enumeration. (The names of all enumerations)

The enumeration to retrieve. To see a list of all possible enumeration ids see the GET /enumerations operation.

query Parameters
includeSchema
boolean

Include the schema of the enumeration. The schema will tell you which members of the enumeration (if any) are editable.

includePermissions
boolean

Include the effective permissions the client has with respect to this enumeration.

header Parameters
Accept-Language
Array of strings
Example: en-US, de-De

The language to use for display text of enumeration name and members. If no language is specified the client's default language as specified in their user profile will be used.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/enumerations/writePriorityEnumSet?includeSchema=false&includePermissions=false' \
  --header 'Accept-Language: en-US, de-De'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example
{
  • "item": {
    }
}

Edit an enumeration (INTERNAL)

Can be used to modify the name of the enumeration and the values of any of the member strings. Cannot be used to add/remove members.

Authorizations:
Bearer-Authentication
path Parameters
id
required
string
Example: customEnumSet30001

The enumeration to edit.

Request Body schema: application/json
required
object

Responses

Request samples

Content type
application/json
Example
{
  • "item": {
    }
}

Response samples

Content type
application/vnd.metasysapi.v4+json
{
  • "item": {
    }
}

Replace an enumeration (INTERNAL)

Replace an enumeration with a new definition. You can not replace a two-state enumeration with a multiple-state enumeration. Nor can you replace a multiple-state enumeration with a two-state enumeration.

Authorizations:
Bearer-Authentication
path Parameters
id
required
string
Example: customEnumSet30001

The enumeration to replace

Request Body schema: application/json
required
object

An enumeration

Responses

Request samples

Content type
application/json
{
  • "item": {
    }
}

Response samples

Content type
application/vnd.metasysapi.v4+json
{
  • "item": {
    }
}

Delete an enumeration (INTERNAL)

Delete an enumeration. Only custom enumerations may be deleted.

Authorizations:
Bearer-Authentication
path Parameters
id
required
string
Example: customEnumSet30001

The enumeration to delete.

Responses

Request samples 

curl --request DELETE \
  --url https:///%7Bhostname%7D/api/v4/enumerations/customEnumSet30001 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

equipment

This section describes the operations you can perform on equipment. Equipment is a broad term for anything that makes a building run, including boilers, chillers, air handling units, lights, meters, and security systems. Use equipment operations to get equipment instances and to list equipment points. Apply filters, sorting, and paging to further refine the results.

Get equipment hosted by a network device

Retrieves the collection of equipment instances hosted by the specified network device or its children. A network device is considered to host an equipment if the equipment defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of equipment instances.

{}

Get equipment instances

Retrieves a collection of equipment instances.

Authorizations:
Bearer-Authentication
query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of equipment instances.

{}

Get a single equipment instance

Retrieves the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A single equipment instance.

{}

Get equipment served by an equipment instance

Retrieves the equipment served by the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of equipment instances.

{}

Get equipment that serve an equipment instance

Retrieves the collection of equipment that serve the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: 04d68394-3415-4813-b5ec-43d840deee38

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/equipment/04d68394-3415-4813-b5ec-43d840deee38/upstreamEquipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of equipment instances.

{}

List equipment points

Retrieves the collection of points that are defined by the specified equipment instance. Each point contains a mapping to an attribute on an object.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "shortName"
Enum: "category" "-category" "equipmentName" "-equipmentName" "isDisplayData" "-isDisplayData" "shortName" "-shortName"
Example: sort=shortName

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/points?page=1&pageSize=100&sort=shortName' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of equipment points

{}

Get equipment serving a space

Retrieves the collection of equipment that serve the specified space.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "type" "-type"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/equipment?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of equipment instances.

{}

network-devices

This section describes the operations you can perform on network devices. Network devices are physical devices such as coordinators and routers that are required for communication between hardware on a computer network. Use network device operations to get, list, and delete network devices. Apply filters, sorting, and paging to further refine the results.

List network devices

Retrieves a collection of network devices.

Authorizations:
Bearer-Authentication
query Parameters
objectType
string
Example: objectType=bacnetIntegrationClass
metasysType: enum
metasysEnum: objectTypeEnumSet

The type of network device to return.

The objectType query parameter cannot be used in conjunction with the classification query parameter.

The acceptable values for this parameter come from the objectTypeEnumSet enumeration. Only the long name of the object type (for example, objectTypeEnumSet.bacnetIntegrationClass instead of bacnetIntegrationClass) is accepted. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

classification
Array of strings
Items Enum: "device" "integration" "server" "controller"
Examples:
  • classification=device&classification=server&classification=controller - Only devices (excludes integrations)
  • classification=device - Only supervisory engines
  • classification=server&classification=device - Servers and supervisory engines

The classification to filter devices on. One or more values are supported.

The classification query parameter cannot be used in conjunction with the objectType query parameter.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/networkDevices?objectType=bacnetIntegrationClass&page=1&pageSize=100&sort=name&classification=device&classification=server&classification=controller' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of network devices.

{}

Get a single network device

Retrieves the specified network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A single network device.

{}

Deletes a network device

Deletes an engine or a server which is a child device of the site director. Cannot be used to delete controllers, integrations, or the site director.

Note: The device must be offline for the operation to succeed.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

Responses

Request samples 

curl --request DELETE \
  --url https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

List network device children

Retrieves the collection of network devices that are children of the specified network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/networkDevices?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of network devices.

{}

Batch request for network devices (PRIVATE)

Allows for batching multiple requests to many network devices.

The following operations relative to a network device are supported:

Relative Path GET POST PUT PATCH DELETE
{networkDeviceId}/certificates/bacnet ✔ ✔ ❌ ❌ ✔
{networkDeviceId}/signingRequests/bacnet ✔ ✔ ✔ ❌ ✔

This batch operation supports up to 1000 requests at a time.

Implementation Notes

The certificate signing request body in responses is base64 encoded PEM content, which is different from the non-batch PEM response.

The schema of the request body is inconsistent with other batch paths. See GIV-108568.

Authorizations:
Bearer-Authentication
Request Body schema: application/json

A collection of individual requests relative to the networkDevices path. All requests will use the same HTTP method and should be for the same resource type relative to the network device.

object or string

An optional shared body for all requests. This will be ignored for any individual request which defines its own body.

required
Array of objects non-empty

An array of individual requests.

Responses

Request samples

Content type
application/json
Example

Create certificate signing requests for multiple devices with the same parameters.

{}

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

Create certificate signing requests for multiple devices with the same parameters.

{
  • "responses": [
    ]
}

List network devices hosting an equipment instance

Retrieves the collection of network devices that host the specified equipment instance, along with the parents of those network devices. A network device hosts an equipment when the equipment defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/networkDevices?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of network devices.

{}

List network devices serving a space

Retrieves the collection of network devices that serve the specified space. A space serves a network device when any equipment instance serving the space defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "categoryId" "-categoryId" "firmwareVersion" "-firmwareVersion" "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/networkDevices?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of network devices.

{}

object queries

A set of built-in queries on objects

Get objects in alarm (INTERNAL)

Retrieves a list of objects for the well known alarm query.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the object. This must be a supervisory device object id for a well known query.

query Parameters
cursor
integer
Example: cursor=243

A handle to next page of data

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/alarm?cursor=243&pageSize=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v4+json

Get all of the objects that are in alarm for the device. The object id needs to be a supervisory device.

{
  • "self": "https://{hostname}/api/v4/objects/{objectId}/objects/wellKnownQuery/alarm?pageSize=2",
  • "next": "https://{hostname}/api/v4/objects/{objectId}/objects/wellKnownQuery/alarm?cursor=47&pageSize=2",
  • "items": [
    ]
}

Get disabled objects (INTERNAL)

Retrieves a list of objects for the well known disabled query.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the object. This must be a supervisory device object id for a well known query.

query Parameters
cursor
integer
Example: cursor=243

A handle to next page of data

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/disabled?cursor=243&pageSize=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v4+json

Get all of the objects that are disabled.

{}

Get offline objects (INTERNAL)

Retrieves a list of objects for the well known offline query.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the object. This must be a supervisory device object id for a well known query.

query Parameters
cursor
integer
Example: cursor=243

A handle to next page of data

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/offline?cursor=243&pageSize=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v4+json

Get all of the objects that are offline.

{}

Get overridden objects (INTERNAL)

Retrieves a list of objects for the well known operator override query.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the object. This must be a supervisory device object id for a well known query.

query Parameters
cursor
integer
Example: cursor=243

A handle to next page of data

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/operatorOverride?cursor=243&pageSize=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v4+json

Get all of the objects that are in operator override.

{
  • "self": "https://{hostname}/api/v4/objects/{objectId}/objects/wellKnownQuery/operatorOverride?pageSize=50",
  • "next": null,
  • "items": [
    ]
}

Get out of service objects (INTERNAL)

Retrieves a list of objects for the well known out of service query.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the object. This must be a supervisory device object id for a well known query.

query Parameters
cursor
integer
Example: cursor=243

A handle to next page of data

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/outOfService?cursor=243&pageSize=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v4+json

Get all of the objects that are out of service.

{}

Get overridden N2 device objects (INTERNAL)

Retrieves a list of objects for the well known supervisory override query.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the object. This must be a supervisory device object id for a well known query.

query Parameters
cursor
integer
Example: cursor=243

A handle to next page of data

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/supervisoryOverride?cursor=243&pageSize=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v4+json

Get all of the objects that are in supervisory override.

{
  • "self": "https://{hostname}/api/v4/objects/{objectId}/objects/wellKnownQuery/supervisoryOverride?pageSize=50",
  • "next": null,
  • "items": [
    ]
}

Get objects with a trouble status (INTERNAL)

Retrieves a list of objects for the well known trouble query.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 5a22812f-ec51-4c11-ab4a-fc986f94f008

The identifier of the object. This must be a supervisory device object id for a well known query.

query Parameters
cursor
integer
Example: cursor=243

A handle to next page of data

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/5a22812f-ec51-4c11-ab4a-fc986f94f008/objects/wellKnownQuery/trouble?cursor=243&pageSize=100' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v4+json

Get all of the objects that have a trouble status.

{}

object trees

An object tree is a hierarchical structure of objects. Metasys exposes trees in its user interfaces (and this API) to provide a means of discovery and navigation. The built-in tree is the "all items" tree which is also called the network tree. Users can also create their own custom hierarchies of trees. These are called interchangeably user defined trees or user views.

This section of the API provides operations to discover and retrieve the various object trees defined in the system.

List object trees (INTERNAL)

Returns a list of all the navigation trees for objects. This includes the "all-items" tree as well as the user defined trees (user views). The list will contain all of the object trees on the system but the effectivePermissions.canRead property in the response payload will list only those trees that the user can read.

Authorizations:
Bearer-Authentication

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/objects/trees \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{}

Get user view (INTERNAL)

This operation fetches the specified tree.

This operation differs from Get an object in that it actually returns the tree, whereas Get an object returns the object representation of the user view. The object representation contains metadata about the user view (for example, its name, objectCategory and itemReference).

Authorizations:
Bearer-Authentication
path Parameters
treeId
required
string
Example: 71637905-0bf0-5287-8f49-8d90066070fa

The unique object identifier of the tree to retrieve. To discover the set of available treeId values see List object trees.

query Parameters
includePermissions
boolean
Default: false
Example: includePermissions=true

Include effective permissions of the current user with respect to the objects in this tree.

includeConditions
boolean
Default: false
Example: includeConditions=true

Include a condition section in the payload that lists any objects that have been deleted. (In the future this section could be used to indicate any other useful condition flags.)

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/trees/71637905-0bf0-5287-8f49-8d90066070fa?includePermissions=true&includeConditions=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{}

objects

This section describes the operations you can perform on objects. Objects are self-contained functional items in the Metasys system, for a full definition refer to the Metasys System Glossary. Use objects operations to list, create, edit, and delete objects. Apply filters, sorting, and paging to further refine the results. Some operations accept subscriptions, see Change of Value Subscriptions.

(INTERNAL) Some operations have limitations, see Operation Restrictions.

Change of Value Subscriptions

Subscribe for change of value (COV) events to receive updates when attribute values change. Currently, subscriptions are available for Get attribute value operations (individual and batch).

Subscribing

To subscribe for COV events, complete the following steps:

  1. Open a stream with the Get a stream operation. Take note of the stream ID.
  2. Use one of the following operations and include a METASYS-SUBSCRIBE header with the stream ID:

Note: Any filters added to the original GET operation also apply to the event subscription.

Unsubscribing

To unsubscribe from a COV event, complete the following steps:

  1. Get the METASYS-SUBSCRIPTION-LOCATION from the subscribe operation response.
  2. Issue a Delete objects subscription request to METASYS-SUBSCRIPTION-LOCATION.

See also:

Events

There are three event types sent by the COV subscription: heartbeat, update, and notification.

  • object.values.heartbeat - A heartbeat event is sent to show that the subscription is still alive. A heartbeat is a JSON string with the current UTC date time in ISO 8601 format and is sent every 30 seconds.

    Heartbeat Payload Example 
    "2021-09-16T19:58:28.5902588Z"

  • object.values.update - An update event is sent when an attribute value changes and the value is included in the event. Here is an example data payload for this type of event. This payload is the same as the payload returned by Get attribute value, except for the inclusion of id and itemReference in the item object. The overall schema for this payload is identical to the Get an object schema (except this payload has no schema or effectivePermissions properties).

    Update Payload Example 
    {
  "item": {
    "presentValue": 76.5,
    "id": "960534d2-7df5-5ed8-884c-164e7a2f280a",
    "itemReference": "{hostname}:{deviceHostname}/AV1"
  },
  "condition": {
    "presentValue": {
      "reliability": "reliabilityEnumSet.reliable",
      "priority": "writePriorityEnumSet.priorityDefault"
    }
  }
}

  • object.values.notification - A notification event is sent when a value has changed but the value is not included in the payload. This happens for some values that are not simple scalar values. You can use this event as a trigger to reread the attribute.

    In the following example, even though the payload does not include the current value, you know which object this is for (based on id and itemReference), and you know it is the overrideExpirationTime attribute based on the attribute property.

    Notification Payload Example 
    {
  "item": {
    "id": "960534d2-7df5-5ed8-884c-164e7a2f280a",
    "itemReference": "{hostname}:{deviceHostname}/AV1"
  },
  "condition": {
    "overrideExpirationTime": {
      "reliability": "reliabilityEnumSet.reliable",
      "priority": "writePriorityEnumSet.priorityNone"
    }
  },
  "attribute": "attributeEnumSet.overrideExpirationTime"
}

Operation Restrictions (INTERNAL)

There are restrictions on certain operations that are not otherwise communicated by the API. These are documented in the following requirements and restrict the creation of certain objects and the writing of certain attributes.

Object Type Forbidden Create Forbidden Attribute Writes
Interlock [G4R-4055][] [G4R-4054][] - actionTbl1, actionTbl2, commandsPriority, source
MCO [G4R-4057][] [G4R-4056][] - actionTbl1, commandsPriority
DLLR n/a [G4R-4053][] - loadList
System n/a [G4R-4060][] - attributeInfo, fileName, logicSequence

The attributes of the System object should be marked readOnly in the schema and a CR (G4CR-8324) is written up for that. The other restrictions are intended to be removed in a future release.

List objects

Returns the root object of the tree and, optionally, its children. The root object is the site object. The default response is a tree representation. Set flatten=true to flatten the tree into a list representation. The number of levels returned depends on the value of the depth parameter. To get just the root of the tree use a depth of 0. Values of depth greater than 1 are not allowed on this endpoint.

Authorizations:
Bearer-Authentication
query Parameters
depth
integer [ 0 .. 1 ]
Default: 1
Example: depth=1

The depth of the tree to return. The provided value is ignored if pathTo, objectType, or classification are specified.

flatten
boolean
Default: false

A value of true indicates the response payload should be a flat list. A value of false (the default) indicates the response payload should be a tree with child objects nested under their parent object. While this parameter influences the shape of the response, it does not affect the content. The same set of objects is returned no matter the value of this parameter.

includeExtensions
boolean
Default: false

A value of true indicates that extension objects should be included in the result. A value of false (the default) indicates that they should not be included.

This parameter is ignored if pathTo is specified.

pathTo
string
Example: pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a

This parameter causes the response to contain the object specified by this parameter, the root object, and the objects in between.

If this parameter is specified, then depth and includeExtensions are ignored.

includeInternal
boolean
Default: false
visibility: internal

(INTERNAL) A value of true indicates that internal objects should be included in the result. A value of false (the default) indicates that they should not be included.

includeEffectivePermissions
boolean
Default: false
Example: includeEffectivePermissions=true

Include the effectivePermissions property in the response payload. This property describes which objects in the response the current user can view, modify or delete.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects?depth=1&flatten=false&includeExtensions=false&pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a&includeInternal=false&includeEffectivePermissions=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

The objects are returned in a tree structure. Child objects are nested under their parents.

{}

Create object

Creates a new object. Several things are needed to successfully create an object. You must know

  • the type of object you want to create
  • if that object type is supported in the location you want to create it
  • what properties can be set on that type of object when creating it
  • what properties are required to be set.

Find the complete list of object types with the operation GET /schemas/enums/objectTypeEnumSet. To determine the specific set of objects that can be created in a location use List supported child types (GET /objects/{objectId}/supportedChildTypes). To discover what object properties can be set and which are required when creating an object use Get a schema for an object type (GET /schemas/objectTypes/{objectType})

See also:

Authorizations:
Bearer-Authentication
Request Body schema: application/json
parentId
required
string

The ID of the parent object. The new object will be created under this object.

localUniqueIdentifier
required
string^[^\x00-\x1F\x7F\x22#'*,.\/:<>?@\[\\\]|]+$

A string that is locally unique within the context of the parent object for identifying the new object. This string will be the last component of the itemReference of the newly created object. For example, assume you have a folder with an itemReference of adx:oas/Programming. Then you create an AV with a local unique identifier of ZN-3-T within that folder. The newly created object will have an itemReference of adx:oas/Programming.ZN-3-T.

The value must not contain any control characters or any of the following characters: " # ' * , . / : < > ? @ [ \ ] |

objectType
required
string
metasysType: enum
metasysEnum: objectTypeEnumSet

The type of object to create.

The values for this property come from the objectTypeEnumSet enumeration. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

item
object

The item object is where you set the properties of the newly created object. Which properties can be set and their data types can be discovered by using the Get schema for object type operation.

This property may or may not be required depending on the object you are creating. Some objects have defaults for all properties and require nothing to be set when creating them. Others have required properties that must be set at creation time.

Responses

Request samples

Content type
application/json
Example

This request body creates a new object of type objectTypeEnumSet.avClass under a folder with an identifier of 82b6f2d5-6fed-5074-b611-94dd40028312 with a locally unique identifier of ZN-3-SETPT. The properties on the new object are name, description, objectCategory, minPresValue and maxPresValue.

{
  • "parentId": "82b6f2d5-6fed-5074-b611-94dd40028312",
  • "localUniqueIdentifier": "ZN-3-SETPT",
  • "objectType": "objectTypeEnumSet.avClass",
  • "item": {
    }
}

List child objects

Returns the specified object and optionally one or more levels of the tree under the object. The default response is a tree representation. Set flatten=true to flatten the tree into a list representation.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 767d8af0-163f-552c-ba37-a884466075f9

Specifies the root of the subtree to return for this request. The objectId is the identifier of the object to retrieve (optionally along with 1 or more levels of descendants).

query Parameters
depth
integer >= -1
Default: 1
Example: depth=1

The depth of the tree to return. For typical usage, a value or 1 or 2 is recommended. Use -1 for maximum depth.

The provided value is ignored if pathTo, objectType, or classification are specified.

flatten
boolean
Default: false

A value of true indicates the response payload should be a flat list. A value of false (the default) indicates the response payload should be a tree with child objects nested under their parent object. While this parameter influences the shape of the response, it does not affect the content. The same set of objects is returned no matter the value of this parameter.

includeExtensions
boolean
Default: false

A value of true indicates that extension objects should be included in the result. A value of false (the default) indicates that they should not be included.

This parameter is ignored if pathTo is specified.

pathTo
string
Example: pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a

This parameter filters the response down to just containing the object specified by this parameter, the object specified by objectId in the path, and the objects in between.

If this parameter is specified, then depth, includeExtensions, objectType and classification are ignored.

objectType
string
Examples:
  • objectType=objectTypeEnumSet.avClass - Analog Value Object Type
  • objectType=objectTypeEnumSet.bvClass - Binary Value Object Type
  • objectType=objectTypeEnumSet.mvClass - Multiple Value Object Type
metasysType: enum
metasysEnum: objectTypeEnumSet

Type of objects to include in the response. This parameter may be repeated. To search for all AV and AI objects one would specify /objects?type=objectTypeEnumSet.avClass&type=objectTypeEnumSet.aiClass.

The use of this parameter overrides depth to -1 and includeExtensions to true.

It is an error to specify this parameter if classification is specified.

The response will include the specified object, the objects that match the objectType for the given depth and any objects in between (like folders and devices).

The acceptable values for this parameter come from the objectTypeEnumSet enumeration. It is acceptable to use the short name of the object type (for example, avClass instead of objectTypeEnumSet.avClass) because the enumeration set is known from context. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

classification
string
Enum: "object" "device" "integration" "controller" "point" "site" "navList" "extension" "folder" "reference" "server" "archive"
Examples:
  • classification=object - Any object not classified by one of the other classification values
  • classification=device - An object that represents a supervisory controller
  • classification=controller - An object that represents a field controller

Filter objects to those with the specific classification. The use of this parameter overrides depth to -1 and includeExtensions to true. It is an error to specify this parameter if objectType is specified.

includeInternal
boolean
Default: false
visibility: internal

(INTERNAL) A value of true indicates that internal objects should be included in the result. A value of false (the default) indicates that they should not be included.

includeEffectivePermissions
boolean
Default: false
Example: includeEffectivePermissions=true

Include the effectivePermissions property in the response payload. This property describes which objects in the response the current user can view, modify or delete.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/767d8af0-163f-552c-ba37-a884466075f9/objects?depth=1&flatten=false&includeExtensions=false&pathTo=a5885077-9dba-5923-a6d8-ae4aabdc6f0a&objectType=objectTypeEnumSet.avClass&classification=object&includeInternal=false&includeEffectivePermissions=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

The objects are returned in a tree structure. Child objects are nested under their parents.

{}

Get object id

Finds the object identifier (the id property of an object) for the object with the specified fully qualified reference (fqr).

Authorizations:
Bearer-Authentication
query Parameters
fqr
required
string
Examples:
  • fqr=adx:adx - An example of a site director fqr
  • fqr=adx:nae23/Programming.AV1 - An example an analog value object fqr
format: fully-qualified-reference

The fully qualified reference of an object.

Fully qualified references use characters that must be escaped when used as query parameters. Most HTTP libraries do this for you automatically. However, if you are using curl or PowerShell where you specify the full URL yourself you may need to be aware. For example, here is the URL to use with curl for a reference of oas:oas/Programming.AV3: https://{hostname}/api/v4/objectIdentifiers?fqr=oas%3Aoas%2FProgramming.AV3

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objectIdentifiers?fqr=adx%3Aadx' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
"32cfddc0-411f-5b9e-9a6d-442cb62fecbb"

Get an object

Objects support one or more views. By default, this operation gets the default view of an object. For many objects this is the Focus View (identifier viewNameEnumSet.focusView). To see the list of views an object supports see List Views (/objects/{objectId}/views). To get a different view of an object specify a value for the viewId parameter.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

  • List Views for information on retrieving the view collection of an object.
Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
viewId
string
Examples:
  • viewId=viewNameEnumSet.focusView - Focus View
  • viewId=viewNameEnumSet.diagnosticView - Diagnostic View
metasysEnum: viewNameEnumSet

The view to retrieve.

This parameter is optional and if it is not specified the default view for the object will be returned. For many objects this is the Focus view (focusView).

The acceptable values for this parameter come from the viewNameEnumSet enumeration. It is acceptable to use the short name of the view (for example, focusView instead of viewNameEnumSet.focusView) because the enumeration set is known from context. Find the definition of viewNameEnumSet at the relative URL of /schemas/enums/viewNameEnumSet.

See also:

includeSchema
boolean

Every object can have a unique schema. Set this parameter to true to include the schema for this object in the response payload.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb?viewId=viewNameEnumSet.focusView&includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

This is an example of an AV object without a schema. Notice that the presentValue is 105 but the maxPresValue is set to 100. This results in the presentValue attribute going unreliable. This can be seen in the condition object where presentValue has a reliability value of reliabilityEnumSet.unreliableHigh. We can also see that the current priority for presentValue is set to writePriorityEnumSet.priorityCriticalEquipment.

{}

Edit an object

This operation modifies one or more attributes of an object. Note: attributes must be updated in whole. For example, if you wish to modify an attribute of metasysType struct which is modelled as a JSON object you must include all elements of the struct. It is undefined what might happen if you do not. The write could fail, the non-mentioned members may get their default value or something else. This applies to any attribute that has a JSON type of array or object. The entire attribute value must be written even if you only wish to change one part of the value.

The request body contains an item property which contains one or more properties and their new values.

The attributes of an object (and their schemas) can be discovered by looking at the different views of an object or by requesting all of the attributes.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Request Body schema: application/json
item
object

The attributes to update.

Responses

Request samples

Content type
application/json
Example
{
  • "item": {
    }
}

Delete an object

Deletes the specified object.

Not all objects can be deleted (not even by an administrator). Examine the effectivePermissions of an object to determine if it can be deleted by the current user.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request DELETE \
  --url https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

List the views of an object

Objects support one or more views. Each view of an object contains a logical grouping of the object's attributes. This operation lists the collection of views that an object has.

Each entry in the response contains the id of a view, and also the absolute URL used to request that view. Use Get an object (/objects/{objectId}) to request a specific view by specifying the desired id for the viewId query parameter.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
includeSchema
boolean

Set this parameter to true to include a schema in the response.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/views?includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

Get public view (INTERNAL)

Returns a set of attributes for an object. The attributes returned are considered public information for any authenticated user and therefore no special privileges are required to call this operation.

One of the attributes returned by this operation (for many objects) is the default attribute (defaultAttribute). If the object has a default attribute then the attribute named by the defaultAttribute property is also included in the response. For example, the analog value (AV) object has a defaultAttribute of attributeEnumSet.presentValue so presentValue is included in the public view of an AV.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
includeSchema
boolean

Every object can have a unique schema. Set this parameter to true to include the schema for this object in the response payload.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/publicView?includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

This is an example of a public view for an AV object with schema included.

{
  • "self": "https://{hostname}/api/v4/objects/960534d2-7df5-5ed8-884c-164e7a2f280a/publicView?includeSchema=true",
  • "objectType": "objectTypeEnumSet.avClass",
  • "parentUrl": "https://{hostname}/api/v4/objects/4d762b40-b3f5-5bed-bba9-d5820993cea7",
  • "objectsUrl": "https://{hostname}/api/v4/objects/960534d2-7df5-5ed8-884c-164e7a2f280a/objects",
  • "networkDeviceUrl": "https://{hostname}/api/v4/networkDevices/4d762b40-b3f5-5bed-bba9-d5820993cea7",
  • "pointsUrl": "https://{hostname}/api/v4/objects/960534d2-7df5-5ed8-884c-164e7a2f280a/points",
  • "trendedAttributesUrl": "https://{hostname}/api/v4/objects/960534d2-7df5-5ed8-884c-164e7a2f280a/trendedAttributes",
  • "alarmsUrl": "https://{hostname}/api/v4/objects/960534d2-7df5-5ed8-884c-164e7a2f280a/alarms",
  • "auditsUrl": "https://{hostname}/api/v4/objects/960534d2-7df5-5ed8-884c-164e7a2f280a/audits",
  • "item": {
    },
  • "schema": {
    },
  • "effectivePermissions": {
    },
  • "condition": { }
}

List attributes of an object

Returns an object payload with a JSON schema that contains all of the properties of the object. Each property entry contains only a partial schema for that property. (To discover the full schema of an attribute use /objects/{objectId}?includeSchema=true or /objects/{objectId}/attributes/{attrId}?includeSchema=true

The item section of the payload will contain at most one attribute, the defaultAttribute. The item section will be completely missing if the object does not have a default attribute.

There will be no views or condition sections like a typical object payload.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/attributes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example
{
  • "item": {
    },
  • "schema": {
    }
}

Get attribute value

Returns an object payload containing the specified attribute. Invoke this operation with a valid METASYS-SUBSCRIBE header to create a subscription for changes to that attribute, rather than returning a value. The current value and any updates to the attribute are instead sent over the specified stream.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

attributeId
required
string
Examples:
  • presentValue - The Present Value
  • itemReference - The Fully Qualified reference
metasysEnum: attributeEnumSet

The attribute to read.

The acceptable values for this parameter come from the attributeEnumSet enumeration. Only the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) is accepted. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

query Parameters
includeSchema
boolean

Set this parameter to true to include a schema in the response.

header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/attributes/presentValue?includeSchema=false' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'METASYS-SUBSCRIBE: 40e47e37-0f24-4101-8e1d-de96af4b648b'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example
{
  • "item": {
    },
  • "condition": {
    },
  • "schema": {
    }
}

List commands

Returns a payload that lists all of the commands that an object supports. Each command entry has an invokeUrl property, which is the URL needed to invoke the command. In addition, each command entry has a commandBodySchema property, which is a JSON schema that describes the acceptable payload for the command. Commands are invoked using the HTTP method PUT along with the invokeUrl and acceptable body.

Note: Some objects, such as multi-state values (MV) and binary values (BV), may list a command that has a commandSet property and a property named aggregateCommand with a value of true instead of invokeUrl. This commandSet lists one or more commands. This entry is not a true command but rather provides a hint to graphical user interfaces on how they may want to group the commands of the commandSet under one command name. For example, an MV object lists a command with the identifier commandIdEnumSet.adjustCommand. This is not an actual command on an MV. Instead the actual commands that could be used to present this command in a UI are listed in the commandSet and they have identifiers like commandIdEnumSet.multistate0Command. The Metasys User Interface displays all of these commands as a single adjust command with the titles of the individual commands as the parameter to send.

Licensing Restrictions

Requires Monitoring and Commanding API license.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/commands \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example
{
  • "self": "https://{hostname}/api/v4/objects/960534d2-7df5-5ed8-884c-164e7a2f280a/commands",
  • "items": [
    ],
  • "effectivePermissions": {
    }
}

Send command

Used to send a command to an object. The payloads of commands differ, but they share some similarities. To learn the specifics of the commands of an object use List commands.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

commandId
required
string
Example: adjustCommand
metasysEnum: commandIdEnumSet

The identifier of the command to send.

The acceptable values for this parameter come from the commandIdEnumSet enumeration. It is acceptable to use the short name of the command identifier (for example, adjustCommand instead of commandIdEnumSet.adjustCommand) because the enumeration set is known from context. Find the definition of commandIdEnumSet at the relative URL of /schemas/enums/commandIdEnumSet.

See also:

Request Body schema: application/json

The body of a command is defined by the commandBodySchema. The commandBodySchema is a property of every command returned by the List commands operation.

priority
string (write-priority-enum-set)
Enum: "writePriorityEnumSet.priorityNone" "writePriorityEnumSet.priorityManualEmergency" "writePriorityEnumSet.priorityFireApplications" "writePriorityEnumSet.priority3" "writePriorityEnumSet.priority4" "writePriorityEnumSet.priorityCriticalEquipment" "writePriorityEnumSet.priorityMinimumOnOff" "writePriorityEnumSet.priorityHeavyEquipDelay" "writePriorityEnumSet.priorityOperatorOverride" "writePriorityEnumSet.priority9" "writePriorityEnumSet.priority10" "writePriorityEnumSet.priorityDemandLimiting" "writePriorityEnumSet.priority12" "writePriorityEnumSet.priorityLoadRolling" "writePriorityEnumSet.priority14" "writePriorityEnumSet.prioritySchedulingOst" "writePriorityEnumSet.priorityDefault"
metasysType: enum
metasysEnum: writePriorityEnumSet
parameters
Array of any >= 0 items
annotation
string

Responses

Request samples

Content type
application/json
Example

This body is used with the adjust command of an Analog Value (AV). It sends the value 72.5 along with an annotation about why the command was invoked. The URL for this command is /objects/{objectId}/commands/adjustCommand

{
  • "parameters": [
    ],
  • "annotation": "Increase the set point to make it warmer."
}

Response samples

Content type
application/vnd.metasysapi.v4+json
"Success"

List supported child types

Many objects support nested objects. The obvious examples of this are folder objects and device objects. Less obvious examples include objects like analog value and multi-state value objects (which can have child objects like integrations). This operation lists the types of objects that can be created under an object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/supportedChildTypes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

The supported child types of a folder.

[
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    },
  • {
    }
]

List object equipment points

Retrieves all equipment points mapped to attributes of this object.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "shortName"
Enum: "category" "-category" "equipmentName" "-equipmentName" "isDisplayData" "-isDisplayData" "shortName" "-shortName"
Example: sort=shortName

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/points?page=1&pageSize=100&sort=shortName' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{}

Batch operations

This operation is used to invoke multiple operations in a single HTTP request. Often a batch request is more efficient than sending each individual operation in its own HTTP request.

In this version of the API, the only objects related operation that can be used in a batch is Get attribute value.

If this operation is invoked with a valid METASYS-SUBSCRIBE header it will cause a subscription to be created for the attributes in the request and rather than returning any values, the current values and any updates to the attributes will be sent over the specified stream.

Licensing Restrictions

Requires Monitoring and Commanding API license.

See also:

Authorizations:
Bearer-Authentication
header Parameters
METASYS-SUBSCRIBE
string
Example: 40e47e37-0f24-4101-8e1d-de96af4b648b

If present, subscribes the client for streaming events associated with the resource. The value of this header is a stream id obtained by opening a stream with Get a stream. The response will have a METASYS-SUBSCRIPTION-LOCATION header which identifies the created subscription.

See also:

Request Body schema: application/json
method
required
string
Value: "GET"

The HTTP method to use for each request. This property is restricted to GET for this version of the API since Get attribute value is the only operation supported in a batch.

required
Array of objects non-empty

A collection of entries that represent the operations to invoke.

Responses

Request samples

Content type
application/json

This example shows a request body that will read the presentValue and status from 3 different objects using sequential numbers as request identifiers.

This example shows the use of sequential numeric values used as request identifiers but any unique strings can be used.

{
  • "method": "GET",
  • "requests": [
    ]
}

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

This example shows the response to a read multiple attributes request. Each operation response is uniquely identified by the corresponding identifier (id) from the request.

{
  • "responses": [
    ]
}

🛠 Create objects in bulk (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

This is a bulk operation that creates one or more objects.

comments: Originally available at v2. May have issues as its design was never reviewed by architects. It was created to support the bulk creation of mapper objects after a discover process was done. However, it is not constrained to create only mapper objects. For example, MUI uses it to create extensions on mapper objects as part of the discovery and creation process.
Authorizations:
Bearer-Authentication
Request Body schema: application/json
Array
parentId
required
string

The ID of the parent object. The new object will be created under this object.

localUniqueIdentifier
required
string^[^\x00-\x1F\x7F\x22#'*,.\/:<>?@\[\\\]|]+$

A string that is locally unique within the context of the parent object for identifying the new object. This string will be the last component of the itemReference of the newly created object. For example, assume you have a folder with an itemReference of adx:oas/Programming. Then you create an AV with a local unique identifier of ZN-3-T within that folder. The newly created object will have an itemReference of adx:oas/Programming.ZN-3-T.

The value must not contain any control characters or any of the following characters: " # ' * , . / : < > ? @ [ \ ] |

objectType
required
string
metasysType: enum
metasysEnum: objectTypeEnumSet

The type of object to create.

The values for this property come from the objectTypeEnumSet enumeration. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

item
object

The item object is where you set the properties of the newly created object. Which properties can be set and their data types can be discovered by using the Get schema for object type operation.

This property may or may not be required depending on the object you are creating. Some objects have defaults for all properties and require nothing to be set when creating them. Others have required properties that must be set at creation time.

Responses

Request samples

Content type
application/json

This shows a request to create two mapper objects.

[
  • {
    },
  • {
    }
]

Response samples

Content type
application/vnd.metasysapi.v4+json
[
  • {
    },
  • {
    }
]

Delete object subscription

Delete a subscription to a resource in the objects domain.

Authorizations:
Bearer-Authentication
path Parameters
streamId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The stream identifier that contains the subscription. This is the unique identifier for the client's stream obtained via GET /stream.

subscriptionId
required
string
Example: 626e5ac3-506d-4017-bb8f-973f1c54ddb5

The identifier of the subscription to act upon. This is the unique identifier to the subscription for a specific resource or type of event. This value is found as the last parameter of a METASYS-SUBSCRIPTION-LOCATION header returned for the original subscription request.

Responses

Request samples 

curl --request DELETE \
  --url https:///%7Bhostname%7D/api/v4/objects/streams/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/subscriptions/626e5ac3-506d-4017-bb8f-973f1c54ddb5 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

schemas

A collection of JSON schemas for describing enumerations and object types.

Get enumeration

This operation retrieves the specified enumeration as a JSON schema. The path of this operation appears in several schemas of object payloads.

To get a list of all enumerations fetch the enumerationSetNamesEnumSet:

GET /schemas/enums/enumerationSetNamesEnumSet

See also:

Authorizations:
Bearer-Authentication
path Parameters
enumId
required
string
Examples:
  • writePriorityEnumSet - The write priority enumeration
  • displayPrecisionEnumSet - The display precision enumeration
  • enumerationSetNamesEnumSet - The set of all sets
metasysType: enum

The enumeration to retrieve.

The acceptable values for this parameter come from the enumerationSetNamesEnumSet enumeration. It is acceptable to use the short name of the value (for example, writePriorityEnumSet instead of enumerationSetNamesEnumSet.writePriorityEnumSet) because the enumeration set is known from context. Find the definition of enumerationSetNamesEnumSet at the relative URL of /schemas/enums/enumerationSetNamesEnumSet.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/schemas/enums/writePriorityEnumSet \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example
{
  • "$schema": "http://json-schema.org/draft-07/schema#",
  • "title": "Write Priority",
  • "$id": "https://{hostname}/api/v4/schemas/enums/writePriorityEnumSet",
  • "setId": 1,
  • "oneOf": [
    ]
}

Get object type schema

This endpoint retrieves a schema for a specific objectType. The schema describes the properties that can be set when creating an object of the specific type.

Authorizations:
Bearer-Authentication
path Parameters
objectType
required
string
Examples:
  • objectTypeEnumSet.avClass - AV
  • objectTypeEnumSet.bvClass - BV
  • objectTypeEnumSet.mvClass - MV
metasysEnum: objectTypeEnumSet

The type of object

The acceptable values for this parameter come from the objectTypeEnumSet enumeration. It is acceptable to use the short name of the object type (for example, avClass instead of objectTypeEnumSet.avClass) because the enumeration set is known from context. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

query Parameters
parentId
required
string
Example: parentId=2993aed9-5765-5641-889c-40ec968c8a82

The object under which this new object will be created.

extendedProperty
string
Examples:
  • extendedProperty=attributeEnumSet.presentValue - Present Value
  • extendedProperty=attributeEnumSet.reliability - Reliability
metasysEnum: attributeEnumSet

The attribute to extend.

Indicates which attribute of the parent object the extension should be linked to. Used only for extension objects (like alarm extensions).

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/schemas/objectTypes/objectTypeEnumSet.avClass?parentId=2993aed9-5765-5641-889c-40ec968c8a82&extendedProperty=attributeEnumSet.presentValue' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

This schema describes the properties that can be configured when creating an object of the type avClass.

{
  • "schema": {
    },
  • "views": [
    ]
}

Get object type identification information (PRIVATE)

This operation is used to suggest values for identification properties for the next object created in a specific location of a specific type. The properties in question are name and localUniqueIdentifier. (The localUniqueIdentifier isn't a true object property but it is a query parameter used when creating an object and the value is used to generate the itemReference property of an object.)

Note: there is no guarantee that the suggested values are still available at the time a client decides to use them to create a new object.

Note: For field controller objects, additional properties may also be returned in addition to name and localUniqueIdentifier.

Authorizations:
Bearer-Authentication
path Parameters
objectType
required
string
Examples:
  • objectTypeEnumSet.avClass - AV
  • objectTypeEnumSet.bvClass - BV
  • objectTypeEnumSet.mvClass - MV
metasysEnum: objectTypeEnumSet

The type of object

The acceptable values for this parameter come from the objectTypeEnumSet enumeration. It is acceptable to use the short name of the object type (for example, avClass instead of objectTypeEnumSet.avClass) because the enumeration set is known from context. Find the definition of objectTypeEnumSet at the relative URL of /schemas/enums/objectTypeEnumSet.

See also:

query Parameters
parentObjectId
required
string
Example: parentObjectId=b3ca663c-36c1-584f-9462-83d7b3d0349d

An object ID that specifies the location in which a new object is intended to be created. The response payload will then contain identification values that are valid for that location.

extendedProperty
string
Examples:
  • extendedProperty=attributeEnumSet.presentValue - Present Value
  • extendedProperty=attributeEnumSet.reliability - Reliability
metasysEnum: attributeEnumSet

The attribute to extend.

Indicates which attribute of the parent object the extension should be linked to. Used only for extension objects (like alarm extensions).

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/schemas/objectTypes/objectTypeEnumSet.avClass/identification?parentObjectId=b3ca663c-36c1-584f-9462-83d7b3d0349d&extendedProperty=attributeEnumSet.presentValue' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

This payload includes a schema that describes the name and localUniqueIdentifier properties and includes a default value for each. This default value for localUniqueIdentifier will always be unique for the given location at the time it is requested.

{
  • "schema": {
    }
}

spaces

Operations on space-related resources.

Get spaces served by a network device

Retrieves the collection of spaces served by the specified network device. A space is served by a network device when any equipment instance serving the space defines points that map to an attribute of any object contained on the network device.

Authorizations:
Bearer-Authentication
path Parameters
networkDeviceId
required
string
Example: d9bf66bd-22f8-425b-82a4-44ba153d79c7

The identifier of a network device.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/networkDevices/d9bf66bd-22f8-425b-82a4-44ba153d79c7/spaces?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of spaces.

{}

Get spaces served by an equipment instance

Retrieves the collection of spaces served by the specified equipment instance.

Authorizations:
Bearer-Authentication
path Parameters
equipmentId
required
string
Example: b78fa672-3ec9-4794-bd00-7aeafeb9cde0

The identifier of the equipment instance.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/equipment/b78fa672-3ec9-4794-bd00-7aeafeb9cde0/spaces?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of spaces.

{}

Get spaces

Retrieves a collection of spaces.

Authorizations:
Bearer-Authentication
query Parameters
type
string
Example: type=spaceTypesEnumSet.building
metasysType: enum
metasysEnum: spaceTypesEnumSet

Type of space to return.

The acceptable values for this parameter come from the spaceTypesEnumSet enumeration. Only the long name of the space type (for example, spaceTypesEnumSet.building instead of building) is accepted. Find the definition of spaceTypesEnumSet at the relative URL of /schemas/enums/spaceTypesEnumSet.

See also:

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/spaces?type=spaceTypesEnumSet.building&page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of spaces.

{}

Get a single space

Retrieves the specified space.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6 \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of spaces.

{}

Get space children

Retrieves the collection of spaces that are located within the specified space.

Authorizations:
Bearer-Authentication
path Parameters
spaceId
required
string
Example: bf254f63-2cbb-4195-8c53-a1d6fcbe54f6

The identifier of a space.

query Parameters
page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 1000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "name"
Enum: "itemReference" "-itemReference" "name" "-name" "typeId" "-typeId"
Example: sort=name

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/spaces/bf254f63-2cbb-4195-8c53-a1d6fcbe54f6/spaces?page=1&pageSize=100&sort=name' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json

A page of spaces.

{}

streaming

Your Metasys system works continuously: sensors report current conditions, algorithms make adjustments, and alarms alert operators to potential issues. Streaming is how the Metasys API provides access to these events using the HTML standard server-sent events (SSE). For further information, refer to Mozilla developer guide. In this document, Streaming typically refers to the Metasys feature and stream refers to the concept of the HTTP connection and the flow of data.

Per the standard, a server-sent event usually contains three components, separated by newline, with the last component having a second newline to mark the end of the event.

id: <event id>\n
event: <event type>\n
data: <event data>\n\n
Line Prefix Explanation
id ordering id to enable the "pick up where you left off" reconnection
event message type
data message payload as a JSON string

Example:

id: b6d184ee-e137-44aa-b9b1-14bc704cd25d:1\n
event: hello\n
data: b6d184ee-e137-44aa-b9b1-14bc704cd25d\n\n

Getting Started

To get started, you first need a client. There are SSE clients available in many languages.

Begin by getting a stream. Only one stream is needed regardless of the number of subscriptions you later create. As explained in the documentation for getting a stream, the first event, hello, is a special event because the data field contains your stream ID.

Some operations support the METASYS-SUBSCRIBE header which transforms them from being a single request/response operations into a streaming subscription. The value of the header is the stream ID from the data field of the hello event described above. As an example, refer to the Get Activities operation for more details about this technique. This technique does not apply to every operation. See each operation's description to understand its Streaming capability.

Not all event data is currently exposed by Streaming. Future versions of the API will add further Streaming capabilities.

Streaming Connection Maintenance

There are a few behaviors to be aware of if you want your stream to work beyond the lifetime of the access token used to get your stream.

Keep Events Flowing After Initial Access Token Expiration

Recall that your access token has an expiration time. To keep the stream longer than the lifetime of that access token, be sure to refresh your token just as you would when using non-Streaming portions of the API. Not only will you get a fresh token to use, but internally, your stream expirations are updated to match the expiration time of the new token.

Reconnect and Using the Current Access Token in Reconnect Requests

The server-sent events standard has a provision for reconnecting a lost connection. Call the same get a stream operation but also add the Last-Event-Id header with the id of the last event received. Most clients handle this for you. Metasys continues to buffer events for at least thirty seconds after the connection failure is detected, so you can resume streams that experienced brief outages. If Metasys has cleaned up your buffer or cannot find that id in the recently sent buffer, you will get a 204 response per the SSE specification. Because your existing stream is not resumable, your Last-Event-Id is no longer valid. The recovery path is to start anew by calling get a stream without the Last-Event-Id and subscribe again to data of interest.

One critical aspect of reconnect is ensuring that the reconnect request is done with the current access token. As covered by get a stream, Streaming lets you specify the token in either the Authorization header or query string. This flexibility accommodates a variety of clients. For example, the web browser client, EventSource, does not provide access to request headers, so you have to use the query string.

For EventSource, this however poses an issue because the reconnect attempt will be done against the original URL which has a potentially outdated access token embedded in the query string. For that reason, if you want to use a JavaScript client, consider using the open source EventSource component. The Metasys User Interface (MUI) employs this library to workaround the limitation of the browser's EventSource . When using it, use the Authorization header instead. Keep the options object passed to the constructor so you can update the Authorization property when you refresh your access token.

Assuming:

  1. Your access token is in variable accessToken
  2. Variable streamingUrl is the URL for get a stream
const eventSourceOptions = {
  headers: {
    Authorization = `Bearer ${accessToken}`
  }
};

const eventSource = new $window.EventSourcePolyfill(streamingUrl, eventSourceOptions);

Before token expiration:

  1. Get a refreshed token. Behind the scenes this also refreshes you stream expirations.
  2. Modify eventSourceOptions with new token like example below
eventSourceOptions.headers.Authorization = `Bearer ${newToken}`;

Tips For Other Client Libraries

SSE clients exist in many languages. Inclusion in this section is not an endorsement; however, if you chose one of these clients, these tips may prove useful for ensuring the current token is used for reconnect.

C# - 3ventic EventSource

When using the 3ventic EventSource for C# you will need to use Reflection to update Uri which is a private field within the EventSource that contains the location to get a stream with the access token embedded in the query string.

public static void SetField(Object obj, String fieldName, object value)
{
    Type type = obj.GetType();
    FieldInfo field = type.GetField(
        fieldName,
        BindingFlags.NonPublic | BindingFlags.Instance
    );
    field.SetValue(obj, value);
}

// example usage
Reflector.SetField(eventSource, "Uri", uriWithCurrentToken);

C# - LaunchDarkly EventSource

When using the LaunchDarkly EventSource for C# you will not call the Reset method to attempt a reconnect. Instead, dispose of the EventSource and then create a new instance, passing the the LastEventId from the last message and the URL to get a stream with a current access token embedded as a query string parameter.

Streaming Events

The following are types of events sent by Streaming along with example data payloads for each:

  • hello - Indicates Streaming connection was successful.

    Example Data Payload 
    "b6d184ee-e137-44aa-b9b1-14bc704cd25d"

  • heartbeat - Indicates Streaming connection is alive.

    Example Data Payload 
    "2021-02-16T16:21:10.23Z"

Get a stream

Opens or reconnects a Server Sent Event stream which is a prerequisite for subscribing to any dynamic updates

Authorizations:
Bearer-AuthenticationAPI-Key-Authentication
header Parameters
Last-Event-Id
string
Example: b6d184ee-e137-44aa-b9b1-14bc704cd25d:5

Providing the ID of the last event received enables a briefly broken stream to be resumed

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/stream \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
  --header 'Last-Event-Id: b6d184ee-e137-44aa-b9b1-14bc704cd25d:5'

Stream keep alive (PRIVATE)

Keep all streams associated to the user session alive and open without interruption until the new token expiration or closed by the client.

This is called internally by the various token refresh endpoints to simplify things for users. There is no need for a user to call this.

Authorizations:
Bearer-Authentication

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/stream/keepalive \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

system

Operations to retrieve capabilities and settings as well as modify settings.

Get system capabilities (PRIVATE)

Returns a collection of key/value pairs that describe the capabilities of a site.

Note: At v4 this operation was only exposed at https://{hostname}/api/private-api/v4/system/capabilities rather than the expected path of https://{hostname}/api/v4/system/capabilities

Authorizations:
Bearer-Authentication

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/system/capabilities \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{
  • "items": {
    }
}

Get system settings (PRIVATE)

Returns a set of key/value pairs that describe various system wide settings.

Note: At v4 this operation was only exposed at https://{hostname}/api/private-api/v4/system/settings rather than the expected path of https://{hostname}/api/v4/system/settings

Authorizations:
Bearer-Authentication
query Parameters
includeSchema
boolean
Default: false
Example: includeSchema=true

Indicates whether the schema for the settings should be returned in the response.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/system/settings?includeSchema=true' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{
  • "item": {
    },
  • "schema": {
    }
}

Edit system setting (PRIVATE)

Update an individual system setting.

Note: At v4 this operation was only exposed at https://{hostname}/api/private-api/v4/system/settings/{settingId} rather than the expected path of https://{hostname}/api/v4/system/settings/{settingId}

Authorizations:
Bearer-Authentication
path Parameters
settingId
required
string
Examples:
  • graphics.behaviors.flash.simpleSymbolFlash - Simple Symbol Flash
  • graphics.behaviors.flash.flashType - Flash Type

One of the keys in the response payload returned by Get system settings.

Request Body schema: application/json
item
required
any

A value appropriate for the specific setting.

Responses

Request samples

Content type
application/json
Example

This request body example will set the value of a setting to true. This would be an appropriate request body for any boolean setting.

{
  • "item": true
}

time series

Operations to retrieve time series data.

Time series data is located in two places: in buffers on devices and in an historical data repository (if your site has a repository).

The buffers typically have relatively recent samples while the repository may have samples as old as your site. Over time the samples in buffers are moved to the repository (if configured to do so).

The samples in buffers are associated with Metasys objects that currently exist on your site. The samples that reside within the repository are also usually associated with objects that exist on your site, but it maintains samples even if the associated objects are deleted. Therefore there may be samples in the repository that are no longer associated with any object on your site.

The time series operations that have paths that begin with /objects only work with objects that exist on the site. When you fetch samples with these operations they will read data from both device buffers and the repository as needed.

The time series operations that have paths that begin with /timeSeries retrieve any historical data that is in the repository regardless of whether the associated object still exists or not. They never retrieve any samples from device buffers.

Get object attributes with samples

Retrieves a collection of attributes under the specified object for which samples are available.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Get samples for an object attribute

Retrieves a collection of samples for the specified object attribute during a particular date and time range.

Note: The parent endpoint /objects/{objectId}/trendedAttributes/{attributeId} is not currently supported.

Authorizations:
Bearer-Authentication
path Parameters
objectId
required
string
Example: 32cfddc0-411f-5b9e-9a6d-442cb62fecbb

The identifier of the object.

attributeId
required
string
Example: presentValue
metasysType: enum
metasysEnum: attributeEnumSet

The identifier of the attribute.

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 1000
Example: pageSize=1000

The maximum number of items to return in the response.

sort
string
Default: "timestamp"
Enum: "timestamp" "-timestamp"
Example: sort=timestamp

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/objects/32cfddc0-411f-5b9e-9a6d-442cb62fecbb/trendedAttributes/presentValue/samples?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=1000&sort=timestamp' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

Single page get samples response containing only analog values.

{}

Get network device attributes with samples

Retrieves a collection of attributes under the specified network device for which samples are available.

Authorizations:
Bearer-Authentication
path Parameters
id
required
string
Example: 6b092d2e-c795-4e90-95e8-5acafc74f19d

The identifier of the network device.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/networkDevices/6b092d2e-c795-4e90-95e8-5acafc74f19d/trendedAttributes \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Get samples for a network device attribute

Retrieves a collection of samples for the specified network device attribute during a particular date and time range.

Note: The parent endpoint /networkDevices/{id}/trendedAttributes/{attributeId} is not currently supported.

Authorizations:
Bearer-Authentication
path Parameters
id
required
string
Example: c550095d-ee4c-4314-b415-b0577e383ee9

The identifier of the network device.

attributeId
required
string
Example: presentValue
metasysType: enum
metasysEnum: attributeEnumSet

The identifier of the attribute.

The acceptable values for this parameter come from the attributeEnumSet enumeration. It is acceptable to use the short name of the attribute (for example, presentValue instead of attributeEnumSet.presentValue) because the enumeration set is known from context. Find the definition of attributeEnumSet at the relative URL of /schemas/enums/attributeEnumSet.

See also:

query Parameters
startTime
string <date-time>
Example: startTime=2018-05-21T13:58:20.243Z

Only include results generated on or after this date-time.

endTime
string <date-time>
Example: endTime=2018-05-21T13:58:20.243Z

Only include results generated on or before this date-time.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 10000 ]
Default: 1000
Example: pageSize=1000

The maximum number of items to return in the response.

sort
string
Default: "timestamp"
Enum: "timestamp" "-timestamp"
Example: sort=timestamp

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/networkDevices/c550095d-ee4c-4314-b415-b0577e383ee9/trendedAttributes/presentValue/samples?startTime=2018-05-21T13%3A58%3A20.243Z&endTime=2018-05-21T13%3A58%3A20.243Z&page=1&pageSize=1000&sort=timestamp' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example

Single page get samples response containing only analog values.

{}

List historical time series (PRIVATE)

The operation retrieves a collection of resources for which historical time series data exists. This operation uses the time series repository as its source of truth. It may contain data for objects that no longer actually exist on the site. This operation never considers time series that exist exclusively in buffers on devices and that are not configured to forward their samples to the repository.

Authorizations:
Bearer-Authentication
query Parameters
searchString
string
Examples:
  • searchString=AV - Find all references with `AV`` in them
  • searchString=Programming - Find all references with `Programming`` in them

Filter results by finding objects with an itemReference that contains the searchString as a substring.

page
integer >= 1
Default: 1
Example: page=1

The page number of items to return.

pageSize
integer [ 1 .. 2000 ]
Default: 100
Example: pageSize=100

The maximum number of items to return in the response.

sort
string
Default: "itemReference"
Enum: "itemReference" "-itemReference"
Example: sort=itemReference

The criteria to use when sorting results (see rules).

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/timeSeries?searchString=AV&page=1&pageSize=100&sort=itemReference' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{}

users

This section describes the operations you can perform on users and roles.

🛠 List users (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Retrieves a collection of users.

Authorizations:
Bearer-Authentication
query Parameters
roles
Array of strings
Example: roles=USER&roles=OPERATOR

Filter by role. The list of roles can be found by calling GET /roles.

See also:

userLastLoggedinAfter
string <date-time>
Example: userLastLoggedinAfter=2022-08-05T05:00:00Z

Only include users that have logged in after this date-time.

userLastLoggedinBefore
string <date-time>
Example: userLastLoggedinBefore=2022-08-05T05:00:00Z

Only include users that have logged in before this date-time.

excludeMetasysUsers
boolean
Default: false
Example: excludeMetasysUsers=true

Indicates if metasys (local) user accounts should be excluded from the results.

Note: You will get a 400 (BadRequest) status code if you set this to true and active directory authentication is not enabled.

excludeRadiusUsers
boolean
Default: false
Example: excludeRadiusUsers=true

Indicates if RADIUS user accounts should be excluded from the results.

excludeADUsers
boolean
Default: false
Example: excludeADUsers=true

Indicates if active directory user accounts should be excluded from the results.

q
string
Example: q=true

A search string used to filter results. At a minimum userName and description properties of a user account are searched.

page
integer
Default: 1
Example: page=3

Results are returned in paged collections. This parameter specifies which page to return.

pageSize
integer
Default: 100
Example: pageSize=50

Results are returned in paged collections. This parameter specifies how many results to include per page.

sort
string
Default: "userName"
Enum: "fullName" "-fullName" "lastLogin" "-lastLogin" "primaryEmail" "-primaryEmail" "userName" "-userName"
Example: sort=userName

The criteria to use when sorting results (see rules).

format
string
Enum: "pdf" "csv"
Example: format=csv

The normal response is JSON. Use the format parameter to request a pdf or csv response.

Responses

Request samples 

curl --request GET \
  --url 'https:///%7Bhostname%7D/api/v4/users?roles=USER&roles=OPERATOR&userLastLoggedinAfter=2022-08-05T05%3A00%3A00Z&userLastLoggedinBefore=2022-08-05T05%3A00%3A00Z&excludeMetasysUsers=true&excludeRadiusUsers=true&excludeADUsers=true&q=true&page=3&pageSize=50&sort=userName&format=csv' \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{}

🛠 Get user (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Retrieves a specific user account.

This operation requires admin privileges.

Authorizations:
Bearer-Authentication
path Parameters
userId
required
string
Example: anNtaXRo

The identifier of the user to retrieve.

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/users/anNtaXRo \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
Example
{
  • "userName": "jsmith",
  • "profile": {},
  • "permissions": {
    },
  • "roles": null,
  • "userViews": {
    }
}

🛠 Edit user (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Edit a user

comments: This operation is very problematic. The request body is an exact duplicate of the response body of GET /users/{userId}. And that body has some properties duplicated (even more than once). So it's not at all obvious what happens if you change one of those properties; but in only one location. It's also not clear what properties are required, what their defaults might be. This will need to be fixed before every making public or internal.
Authorizations:
Bearer-Authentication
path Parameters
userId
required
string
Example: anNtaXRo

The identifier of the user to retrieve.

Request Body schema: application/json
userName
string
object
object
object or null
object

Responses

Request samples

Content type
application/json
{
  • "userName": "api-user",
  • "profile": {},
  • "permissions": {
    },
  • "roles": null,
  • "userViews": {
    }
}

🛠 Get current user (PRIVATE)

Note: This entry is a stub. It is incomplete and may be missing details like descriptions, examples, parameters, schemas, schema details or other information.

Get information about the user account of the current session.

Authorizations:
Bearer-Authentication

Responses

Request samples 

curl --request GET \
  --url https:///%7Bhostname%7D/api/v4/userinfo \
  --header 'Authorization: Bearer REPLACE_BEARER_TOKEN'

Response samples

Content type
application/vnd.metasysapi.v4+json
{
  • "userName": "api-user",
  • "profile": {},
  • "permissions": {
    },
  • "roles": null,
  • "userViews": {
    }
}